@dossier/deepl-tools

DeepL translation tools with Dossier ProFile defaults — MCP server and CLI.

Wraps the DeepL API with automatic glossary resolution and formality settings tuned for Dossier's supported languages. Works as a standalone CLI or as an MCP server for AI coding assistants.

Install

npm install @dossier/deepl-tools

Requires a DeepL API key linked to the Dossier organization account (for glossary access). Get one assigned by your leader, or retrieve it from AWS Secrets Manager.

MCP Server

Exposes three tools: translate-text, translate-document, and rephrase-text.

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "dossier-deepl": {
      "command": "npx",
      "args": ["-p", "@dossier/deepl-tools", "dossier-deepl-mcp"],
      "env": {
        "DOSSIER_DEEPL_API_KEY": "your-key"
      }
    }
  }
}

Or register via the Claude Code CLI:

claude mcp add dossier-deepl -e DOSSIER_DEEPL_API_KEY=your-key -- npx -p @dossier/deepl-tools dossier-deepl-mcp

CLI

Language arguments are locale codes (en_US, nb_NO, …), mapped to DeepL codes at the boundary (see Language Codes below).

# Translate text
dossier-deepl translate "Hello world" --to de_DE

# Multiple targets
dossier-deepl translate "Hello world" --to nb_NO,da_DK,sv_SE,de_DE,fr_FR,es_ES

# With source locale (enables glossary)
dossier-deepl translate "Dialog" --to nb_NO --from en_US

# Pipe from stdin
echo "Complete the training" | dossier-deepl translate --to fr_FR

# Context and custom instructions
dossier-deepl translate "Started" --to de_DE --from en_US \
  --custom-instruction "Translate as a past participle used as a status label"

# JSON output
dossier-deepl translate "Hello" --to nb_NO --format json

# Translate a document
dossier-deepl translate-document report.pdf --to de_DE --output report_de.pdf --format json

# Rephrase text
dossier-deepl rephrase "Their going to the store" --lang en_US

# Rephrase with style or tone (mutually exclusive)
dossier-deepl rephrase "We need to do this ASAP" --lang en_US --style business
dossier-deepl rephrase "We need to do this ASAP" --lang en_US --tone diplomatic

All commands support --format json for programmatic use.

Translate vs. Rephrase options

The DeepL Translate and Write (rephrase) APIs offer different controls:

| Option | Translate | Rephrase | |--------|-----------|----------| | formality | less, more, prefer_less, prefer_more | -- | | customInstructions | free-form directives (de, en, es, fr) | -- | | context | surrounding source text for disambiguation | -- | | style | -- | simple, business, academic, casual (de, en, es, fr, it, pt) | | tone | -- | enthusiastic, friendly, confident, diplomatic (de, en, es, fr, it, pt) |

style and tone are mutually exclusive — only one can be used per request. Both also accept prefer_ variants (e.g. prefer_business) which fall back gracefully for unsupported languages instead of erroring.

Dossier Defaults

These defaults are applied automatically and can be overridden per request:

| Setting | Value | Applies to | |---------|-------|------------| | Formality | prefer_more | de, fr, es | | Glossary | auto-resolved by source locale | when --from is specified and a matching dossier-profile-{locale} glossary exists on DeepL |

Configuration

DOSSIER_DEEPL_API_KEY (required) — your DeepL API authentication key. Falls back to DEEPL_API_KEY if DOSSIER_DEEPL_API_KEY is not set.

Glossary auto-resolution — on startup, the client lists all multilingual glossaries on your DeepL account and matches any named dossier-profile-{locale}. When you specify a source locale (--from / sourceLangCode), the matching glossary is attached automatically. Pass --glossary <id> to override.

Library Usage

The package also exports DossierDeepL for use as a TypeScript/JavaScript library:

import { DossierDeepL } from '@dossier/deepl-tools';

const deepl = new DossierDeepL();          // uses DOSSIER_DEEPL_API_KEY (or DEEPL_API_KEY) env var
// or: new DossierDeepL('your-api-key')    // pass key explicitly

// Single target — arguments are locale codes, mapped to DeepL at the boundary
const result = await deepl.translate('Hello world', 'en_US', 'de_DE');
console.log(result.text); // "Hallo Welt"

// Multiple targets
const results = await deepl.translateMultiple('Hello', 'en_US', ['nb_NO', 'da_DK', 'sv_SE']);
for (const [locale, result] of results) {
  console.log(`${locale}: ${result.text}`);
}

// With options (same as deepl-node TranslateTextOptions)
const custom = await deepl.translate('Started', 'en_US', 'de_DE', {
  customInstructions: ['Translate as a past participle used as a status label'],
});

// Rephrase with style or tone (mutually exclusive)
const rephrased = await deepl.rephrase('We need to do this ASAP', 'en_US', 'business');

// Document translation
const doc = await deepl.translateDocument('report.pdf', 'report_de.pdf', 'en_US', 'de_DE');

All Dossier defaults (glossary resolution, formality) are applied automatically.

Glossary Management

The curated glossary lives at domain/glossary.yaml (repo root). Three npm scripts manage it:

# Push glossary to DeepL as multilingual glossaries (one per source locale)
npm run glossary:push -- --dry-run   # preview what would be created
npm run glossary:push                # push to DeepL

# Compare glossary against ProFile .properties translations
npm run glossary:diff -- --profile /path/to/dossier-profile
npm run glossary:diff -- --profile /path/to/dossier-profile --lang nb_NO,de_DE

# Export glossary as a standalone HTML page
npm run glossary:html

glossary:push creates/replaces dossier-profile-{locale} glossaries on DeepL for each source locale (e.g. dossier-profile-en-us). Requires the deepl CLI.

glossary:diff finds where ProFile .properties translations diverge from the glossary. The glossary is the source of truth — divergences are informational.

glossary:html renders the glossary as a static HTML file (written to output/glossary.html).

Language Codes

All tools use locale codes, mapped to DeepL codes at the boundary: the DeepL source is always the base code, the DeepL target keeps the variant only for English (en_US → en-US), and the glossary name carries the full locale.

| Language | Locale | DeepL source | DeepL target | Glossary name | |----------|--------|--------------|--------------|---------------| | English (US) | en_US | en | en-US | dossier-profile-en-us | | Norwegian Bokmål | nb_NO | nb | nb | dossier-profile-nb-no | | Danish | da_DK | da | da | dossier-profile-da-dk | | Swedish | sv_SE | sv | sv | dossier-profile-sv-se | | German | de_DE | de | de | dossier-profile-de-de | | French | fr_FR | fr | fr | dossier-profile-fr-fr | | Spanish | es_ES | es | es | dossier-profile-es-es |

License

MIT