tpo-deepl

Translate missing entries in .po files using DeepL — and detect duplicates for better translation memory management.

tpo-deepl is a CLI tool for modern gettext-based i18n workflows. It combines:

• ✅ DeepL-based auto-translation for missing msgstr entries.
• ✅ Advanced duplicate detection to identify redundant or overly similar translations.
• ✅ Designed for localization teams who want automation without sacrificing quality.

---

🚀 Installation

Install globally using pnpm:

pnpm install -g tpo-deepl

---

⚙️ Setup

1️⃣ Get your DeepL API key

Sign up at deepl.com/pro — free up to 500,000 characters/month.

2️⃣ Configure your environment

You can either:

# .env file:
DEEPL_API_KEY=your-key-here

or export it directly:

export DEEPL_API_KEY=your-key-here

3️⃣ Create a config file

In your project root, create tpo.config.json or tpo.config.ts:

{
  "localesPath": "./src/locales/{locale}/messages.po",
  "mainLanguage": "de"
}

• Use {locale} placeholder where the language codes are located.
• Make sure your file paths point to valid .po files.

---

🔧 Commands

tpo translate

Auto-translate all missing .po entries using DeepL.

tpo translate [options]

Options

Option	Description
--dry-run	Preview translations without modifying files
--formality <level>	DeepL formality: less, more, prefer_less, prefer_more, default
--only <lang>	Translate only specific language (e.g. fr)
--silent	Suppress output
--config <path>	Use a custom config file instead of default

Examples

Translate all missing entries with formal tone:

tpo translate --formality more

Translate only French:

tpo translate --only fr

Preview changes without modifying files:

tpo translate --dry-run

---

tpo duplicates

Detect duplicate translations inside your .po files.

tpo duplicates [options]

Default mode

By default, detects strict identical msgstr duplicates per language file.

Advanced near-duplicate detection

Option	Description
--words <number>	Minimum consecutive words to match
--similarity <number>	Allow small gaps inside consecutive matches (only with --words)
--only <lang>	Limit scan to specific language
--strict	Fail with non-zero exit code if duplicates are found (CI friendly)

Examples

Detect strict duplicates (default):

tpo duplicates

Detect duplicates with at least 3 consecutive identical words:

tpo duplicates --words 3

Detect duplicates allowing 1 mismatch inside a 3-word sequence:

tpo duplicates --words 3 --similarity 1

Limit detection to German:

tpo duplicates --only de

---

📝 License

MIT