@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": {
        "DEEPL_API_KEY": "your-key"
      }
    }
  }
}

Or register via the Claude Code CLI:

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

CLI

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

# Multiple targets
dossier-deepl translate "Hello world" --to nb,da,sv,de,fr,es

# With source language (enables glossary)
dossier-deepl translate "Dialog" --to nb --from en

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

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

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

# Translate a document
dossier-deepl translate-document report.pdf --to 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 language | when --from is specified and a matching dossier-profile-{lang} glossary exists on DeepL |

Configuration

DEEPL_API_KEY (required) — your DeepL API authentication key.

Glossary auto-resolution — on startup, the client lists all multilingual glossaries on your DeepL account and matches any named dossier-profile-{lang}. When you specify a source language (--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 DEEPL_API_KEY env var
// or: new DossierDeepL('your-api-key')    // pass key explicitly

// Single target
const result = await deepl.translate('Hello world', 'en', 'de');
console.log(result.text); // "Hallo Welt"

// Multiple targets
const results = await deepl.translateMultiple('Hello', 'en', ['nb', 'da', 'sv']);
for (const [lang, result] of results) {
  console.log(`${lang}: ${result.text}`);
}

// With options (same as deepl-node TranslateTextOptions)
const custom = await deepl.translate('Started', 'en', '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', '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 language)
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,de

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

glossary:push creates/replaces dossier-profile-{lang} glossaries on DeepL for each source language. 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 DeepL language codes (ISO 639-1). Regional variants like en-US and en-GB are accepted for targets and resolve to the parent language glossary.

| Language | Code | |----------|------| | English | en | | Norwegian Bokmal | nb | | Danish | da | | Swedish | sv | | German | de | | French | fr | | Spanish | es |

License

MIT