Merge branch 'feat/sync' into 'main'

test(sync): measure bucket-source readFile call count with template patterns

See merge request hack-projects/deepl-cli!2

Author: sjsyrek

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Report a bug in DeepL CLI
+title: 'bug: '
+labels: bug
+assignees: ''
+---
+
+## Summary
+
+A clear, concise description of the bug.
+
+## Environment
+
+- **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)
+
+## Reproduction Steps
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full error output (redact any API keys):
+
+```
+<paste error output here>
+```
+
+## Additional Context
+
+Anything else that might help — config snippets (redacted), example files,
+related issues, workarounds you've tried.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement for DeepL CLI
+title: 'feat: '
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem does this feature solve? Who is affected? What workflow is
+currently painful or impossible?
+
+## Proposed Solution
+
+A clear, concise description of what you'd like to see.
+
+## Alternatives Considered
+
+Other approaches you've thought about and why you believe the proposed
+solution is the best fit.
+
+## Additional Context
+
+Use cases, mockups, related tools, or links to similar features in other
+CLIs.

.gitignore

@@ -66,8 +66,15 @@ logs/
 *.db-wal
 *.db-shm
 
-# Claude Code local settings
-.claude/settings.local.json
+# 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/

CHANGELOG.md

@@ -6,21 +6,25 @@ DeepL CLI is a command-line interface for the DeepL API that integrates translat
 
 ### Current Status
 
-- **Version**: 1.0.0
-- **Tests**: 2757 tests passing (100% pass rate), ~91% coverage
+- **Version**: see `VERSION` file / `package.json`
+- **Tests**: see `npm test` output (target: all green; coverage thresholds enforced by jest config)
 - **Test mix**: ~70-75% unit, ~25-30% integration/e2e
-- **Next Milestone**: 1.0.0 (stable public API)
 
 ### Architecture
 
 ```
-CLI Commands (translate, write, watch, glossary, etc.)
+CLI Commands (translate, write, voice, sync, watch, glossary, tm, …)
            ↓
-Service Layer (Translation, Write, Batch, Watch, GitHooks, Cache, Glossary)
+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)
+           ↓                         ↓
+API Client (Translate, Write, Glossary, Document, Voice,
+            StyleRules, Admin, TMS)
            ↓
-API Client (DeepL API: /v2/translate, /v2/write, /v3/glossaries)
-           ↓
-Storage (SQLite Cache, Config Management)
+Storage (SQLite Cache, Config) + Static Data (src/data — language registry)
 ```
 
 ### Configuration
@@ -98,8 +102,11 @@ Use **Semantic Versioning** with **Conventional Commits**:
 src/
 ├── cli/              # CLI interface and commands
 ├── services/         # Business logic
+├── sync/             # Continuous localization engine (scan, diff, translate, write, lock)
+├── formats/          # i18n file format parsers (JSON, YAML, PO, XLIFF, Android XML, etc.)
 ├── api/              # DeepL API client
-├── storage/          # Data persistence
+├── storage/          # Data persistence (SQLite cache, config)
+├── data/             # Static data (language registry)
 ├── utils/            # Utility functions
 └── types/            # Type definitions
 ```

CLAUDE.md

@@ -195,6 +195,7 @@ Contributions must be licensed under the same license as the project:
 - [ ] `README.md` updated if user-facing feature changed
 - [ ] `docs/API.md` updated if command/flag added or changed
 - [ ] Example script added/updated in `examples/` for new features
+- [ ] Added new example script to `examples/run-all.sh` EXAMPLES array (for new CLI commands)
 
 ## Adding a New CLI Command
 
@@ -227,4 +228,4 @@ When filing a bug report, include:
 - [docs/API.md](./docs/API.md) -- Complete CLI command reference
 - [DeepL API Docs](https://www.deepl.com/docs-api) -- Official API documentation
 
-[issues]: https://github.com/kwey/deepl-cli/issues
+[issues]: https://github.com/DeepLcom/deepl-cli/issues

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 DeepL
+Copyright (c) 2026 DeepL SE
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -10,8 +10,9 @@
 ## 🌟 Key Features
 
 - **🌍 Translation** - High-quality translation using DeepL's next-gen LLM
+- **🔄 Continuous Localization (`deepl sync`)** - Incremental i18n file sync with 11 format parsers
 - **📄 Document Translation** - Translate PDF, DOCX, PPTX, XLSX with formatting preservation
-- **🎙️ Voice Translation** - Real-time speech translation via WebSocket streaming (Voice API)
+- **🎙️ Voice Translation (Pro/Enterprise)** - Real-time speech translation via WebSocket streaming (Voice API)
 - **👀 Watch Mode** - Real-time file watching with auto-translation
 - **✍️ Writing Enhancement** - Grammar, style, and tone suggestions (DeepL Write API)
 - **💾 Smart Caching** - Local SQLite cache with LRU eviction
@@ -31,26 +32,27 @@ For security policy and vulnerability reporting, see [SECURITY.md](SECURITY.md).
   - [Verbose Mode](#verbose-mode)
   - [Quiet Mode](#quiet-mode)
   - [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) | [Voice Translation](#voice-translation)
-  - **Resources:** [Glossaries](#glossaries)
+  - **Resources:** [Glossaries](#glossaries) | [Translation Memories](#translation-memories)
   - **Workflow:** [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)
+  - **Information:** [Usage Statistics](#api-usage-statistics) | [Language Detection](#language-detection) | [Languages](#supported-languages) | [Shell Completion](#shell-completion) | [Command Suggestions](#command-suggestions)
   - **Administration:** [Admin API](#admin-api)
 - [Development](#-development)
 - [Architecture](#-architecture)
+- [Testing](#-testing)
+- [Documentation](#-documentation)
+- [Environment Variables](#-environment-variables)
+- [Security & Privacy](#-security--privacy)
 - [Contributing](#-contributing)
 - [License](#-license)
 
 ## 📦 Installation
 
-### From npm (Coming Soon)
-
-```bash
-npm install -g deepl-cli
-```
-
 ### From Source
 
 ```bash
@@ -69,7 +71,7 @@ npm link
 
 # Verify installation
 deepl --version
-# Output: 1.0.0
+# Output: deepl-cli 1.x.x
 ```
 
 > **Note:** This project uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) for local caching, which requires native compilation. If `npm install` fails with build errors, ensure you have:
@@ -78,6 +80,12 @@ deepl --version
 > - **Linux**: `python3`, `make`, and `gcc` (`apt install python3 make gcc g++`)
 > - **Windows**: Visual Studio Build Tools or `windows-build-tools` (`npm install -g windows-build-tools`)
 
+### From npm (not yet published)
+
+An npm package is not yet published; install from source until then.
+
+> **CI examples below** (and generated hook output) assume a published npm package; source-installed users should substitute the source-install path.
+
 ## 🚀 Quick Start
 
 ### 1. Get Your DeepL API Key
@@ -288,13 +296,13 @@ deepl translate locales/en.json --to es,fr,de --output locales/
 
 **Smart Caching for Text Files:**
 
-Small text-based files (under 100 KB) automatically use the cached text translation API for faster performance and reduced API calls. Larger files automatically fall back to the document translation API (not cached).
+Small text-based files (under 100 KiB) automatically use the cached text translation API for faster performance and reduced API calls. Larger files automatically fall back to the document translation API (not cached).
 
-- **Cached formats:** `.txt`, `.md`, `.html`, `.htm`, `.srt`, `.xlf`, `.xliff` (files under 100 KB only)
+- **Cached formats:** `.txt`, `.md`, `.html`, `.htm`, `.srt`, `.xlf`, `.xliff` (files under 100 KiB only)
 - **Structured formats:** `.json`, `.yaml`, `.yml` — parsed and translated via batch text API (no size limit)
-- **Large file fallback:** Files ≥100 KB use document API (not cached, always makes API calls)
+- **Large file fallback:** Files ≥100 KiB use document API (not cached, always makes API calls)
 - **Binary formats:** `.pdf`, `.docx`, `.pptx`, `.xlsx` always use document API (not cached)
-- **Performance:** Only small text files (<100 KB) benefit from instant cached translations
+- **Performance:** Only small text files (<100 KiB) benefit from instant cached translations
 - **Cost savings:** Only small text files avoid repeated API calls
 
 ```bash
@@ -840,6 +848,8 @@ deepl init
 # - Basic configuration
 ```
 
+> To configure continuous localization for an existing project, see also [`deepl sync init`](#sync-init) or run the wizard directly.
+
 #### Authentication
 
 ```bash
@@ -1040,7 +1050,7 @@ DeepL CLI includes built-in retry logic and timeout handling for robust API comm
 - ✅ Automatic retry on transient failures
 - ✅ Exponential backoff to avoid overwhelming the API
 - ✅ Smart error detection (retries 5xx, not 4xx)
-- ✅ Configurable timeout and retry limits (programmatic API only)
+- ✅ Configurable via library-consumer options; not exposed as a CLI flag
 - ✅ Works across all DeepL API endpoints
 
 **Retry Behavior Examples:**
@@ -1313,7 +1323,7 @@ Cache location: `~/.cache/deepl-cli/cache.db` (or `~/.deepl-cli/cache.db` for le
 
 ### Prerequisites
 
-- Node.js >= 20.0.0
+- Node.js >= 20.19.0
 - npm >= 9.0.0
 - DeepL API key
 
@@ -1387,25 +1397,33 @@ deepl translate "Hello" --to es
 DeepL CLI follows a layered architecture:
 
 ```
-CLI Interface (Commands, Parsing, Help)
-           ↓
-Core Application (Command Handlers, Interactive Shell)
+CLI Commands (translate, write, voice, sync, watch, glossary, tm, …)
            ↓
-Service Layer (Translation, Write, Cache, Watch, Glossary)
+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)
+           ↓                         ↓
+API Client (Translate, Write, Glossary, Document, Voice,
+            StyleRules, Admin, TMS)
            ↓
-API Client (DeepL Translate, Write, Glossary APIs)
-           ↓
-Storage (SQLite Cache, Config, Translation Memory)
+Storage (SQLite Cache, Config) + Static Data (src/data — language registry)
 ```
 
 ### Key Components
 
-- **Translation Service** - Core translation logic with caching and preservation
-- **Write Service** - Grammar and style enhancement
-- **Cache Service** - SQLite-based cache with LRU eviction
-- **Preservation Service** - Preserves code blocks, variables, formatting
-- **Watch Service** - File watching with debouncing
-- **Glossary Service** - Glossary management and application
+- **Translation Service** — core translation with caching and text preservation
+- **Write Service** — grammar, style, and tone suggestions
+- **Voice Service** — real-time speech translation over WebSocket
+- **Sync Engine** — continuous localization: scan, diff, translate, write, lock
+- **Format Parsers** — 11 i18n parsers (JSON, YAML, TOML, PO, Android XML, iOS Strings, xcstrings, ARB, XLIFF, Properties, Laravel PHP) with format-preserving reconstruct
+- **Batch Service** — parallel multi-file translation
+- **Watch Service** — file watching with debouncing
+- **Glossary Service** — glossary management and application
+- **Translation Memory Service** — reuse approved translations (`--translation-memory`)
+- **Cache** — SQLite cache with LRU eviction (`src/storage/cache.ts`)
+- **Preservation utilities** — `src/utils/` helpers for code blocks, variables, and ICU MessageFormat
 
 ## 🧪 Testing
 
@@ -1452,6 +1470,10 @@ npm run examples:fast
 | `DEEPL_CONFIG_DIR` | Override config and cache directory                                                                                  |
 | `XDG_CONFIG_HOME`  | Override XDG config base (default: `~/.config`)                                                                      |
 | `XDG_CACHE_HOME`   | Override XDG cache base (default: `~/.cache`)                                                                        |
+| `HTTP_PROXY`       | HTTP proxy URL for outbound DeepL API traffic                                                                        |
+| `HTTPS_PROXY`      | HTTPS proxy URL (takes precedence over `HTTP_PROXY`)                                                                 |
+| `TMS_API_KEY`      | API key for the configured TMS server (`sync push`/`pull`)                                                           |
+| `TMS_TOKEN`        | Alternative auth token for the configured TMS server                                                                 |
 | `NO_COLOR`         | Disable colored output                                                                                               |
 | `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.                |
@@ -1464,12 +1486,14 @@ See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for
 - **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
-- **GDPR compliant** - Follows DeepL's GDPR compliance guidelines
+- **GDPR-aligned with DeepL's DPA** - Follows DeepL's Data Processing Agreement terms
 
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
+DeepL® is a registered trademark of DeepL SE.
+
 ---
 
 _Powered by DeepL's next-generation language model_

README.md

@@ -1,7 +1,10 @@
+# Security Policy
+
 ## Supported Versions
 
 | Version | Supported          |
 |---------|--------------------|
+| 1.1.x   | :white_check_mark: |
 | 1.0.x   | :white_check_mark: |
 | < 1.0   | :x:                |
 

SECURITY.md

@@ -1 +1 @@
-1.0.0
+1.1.0