doopl

module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 1, 2026 License: MIT

README

doopl

An idiomatic Go client for the DeepL API, usable as a library, CLI, or MCP server for AI clients.

Version: 0.0.1 — initial release. Supports text translation, document translation, glossaries, languages, usage, and text rephrasing (Write API). All public APIs are fully documented with godoc available on pkg.go.dev.

Use with Claude & AI Clients (MCP)

Fastest way to get started: Install doopl as an MCP server for Claude Code, Claude Desktop, or any MCP-compatible AI client.

# Build the MCP server
go build -o doopl-mcp ./cmd/doopl-mcp

# Add to Claude Code settings (.claude/settings.json)
{
  "mcpServers": {
    "doopl": {
      "command": "/path/to/doopl-mcp",
      "args": ["serve"],
      "env": { "DEEPL_AUTH_KEY": "your-key-here" }
    }
  }
}

Now Claude can translate, list languages, and check API usage directly. See AI Integration Guide for setup, examples, and use cases.

Install

go get github.com/arashackdev/doopl

Library usage

Text Translation
client, err := doopl.New(os.Getenv("DEEPL_AUTH_KEY"))
if err != nil {
    log.Fatal(err)
}

results, err := client.TranslateText(ctx, []string{"Hello, world!"}, "DE",
    doopl.WithFormality(doopl.FormalityMore))
if err != nil {
    var apiErr *doopl.Error
    if errors.As(err, &apiErr) && errors.Is(err, doopl.ErrQuotaExceeded) {
        // handle quota specifically
    }
    log.Fatal(err)
}
fmt.Println(results[0].Text) // "Hallo, Welt!"
Document Translation
file, err := os.Open("document.pdf")
defer file.Close()
output, err := os.Create("document_de.pdf")
defer output.Close()

err = client.TranslateDocument(ctx, file, "document.pdf", "DE", output)
Glossaries
entries := model.GlossaryEntries{
    "API":    "Schnittstelle",
    "server": "Server",
}
glos, err := client.CreateGlossary(ctx, "tech-terms", "EN", "DE", entries)

results, err := client.TranslateText(ctx, []string{"The API is fast"}, "DE",
    doopl.WithGlossaryID(glos.GlossaryID))
Rephrase (Write API)
results, err := client.Rephrase(ctx, []string{"Hello!"}, "EN",
    doopl.WithTone(model.WriteToneFormal))
fmt.Println(results[0].Text) // "Greetings!"
Languages & Usage
langs, err := client.SourceLanguages(ctx)
usage, err := client.Usage(ctx)

Free vs. Pro API endpoint is detected automatically from your key (free keys end in :fx). Override with doopl.WithServerURL(...) — also how you point the client at deepl-mock for testing.

AI Integration Guide

What You Can Do

With doopl's MCP server, Claude (or any AI client) can:

  • Translate text — supports all DeepL options (formality, glossaries, context, style, tag handling)
  • List languages — query supported languages for any resource type (translate, document, glossary, write)
  • Check quota — inspect character and document usage before large operations
  • Multi-language workflows — translate documents, test UI localization, route support tickets
Quick Example: Claude + doopl
Human: "Translate this support ticket from German to English and draft a friendly reply"

Claude:
1. Calls translate(text=<ticket>, target_lang=EN)
2. Gets English text: "The login page is broken"
3. Drafts reply: "Thank you for reporting. We're investigating..."
4. Calls translate(text=<reply>, target_lang=DE)  
5. Returns German reply to send to customer
Setup
  1. Build the server:

    task mcp:build  # Creates ./bin/doopl-mcp
    
  2. Configure Claude Code (.claude/settings.json):

    {
      "mcpServers": {
        "doopl": {
          "command": "/full/path/to/bin/doopl-mcp",
          "args": ["serve"],
          "env": { "DEEPL_AUTH_KEY": "your-key" }
        }
      }
    }
    
  3. Restart Claude — it will detect and load the new tools.

Available Tools
Tool What It Does
translate Translate text to a target language, optionally with source language, formality, and glossary
languages List supported languages for translate/document/glossary/write resources
usage Check character and document quota usage

Details: See the full AI Integration Guide for input/output specs, examples, and advanced setup.

CLI usage

go install github.com/arashackdev/doopl/cmd/doopl@latest

export DEEPL_AUTH_KEY=your-key-here

# Translate text
doopl translate --to DE "Hello, world!"

# List supported languages
doopl languages

# Check API usage
doopl usage

The CLI is a thin urfave/cli wrapper — every flag maps directly to a library option. No translation logic lives in cmd/doopl; it's proof the library is genuinely embeddable, not a parallel implementation.

Features

Full DeepL v3 API Coverage
  • ✅ Text Translation — all 8 options (formality, glossary, context, style, tag handling, custom instructions, translation memory, model type)
  • ✅ Document Translation — upload, poll, download with automatic backoff
  • ✅ Glossaries — create, list, get, delete, fetch entries
  • ✅ Languages — list for translate/document/glossary/write resources
  • ✅ Usage — character and document quotas
  • ✅ Write API — rephrase with tone and emoji control
Production Ready
  • Free/Pro endpoint auto-detection from API key
  • Exponential backoff + jitter on rate limits and errors
  • Retry-After header support
  • Context cancellation throughout
  • Sentinel errors with errors.Is/errors.As
  • Concurrent-safe Client
  • Full godoc on all APIs

Architecture

See docs/scope-and-checklist.md for rationale. The project enforces a three-layer separation:

  • apimodel (internal): wire-format types matching the DeepL API exactly
  • model: public, Go-idiomatic domain types
  • entity (CLI): display types for table/JSON output

Each layer is isolated via generated converters (goverter), so changes to the API surface don't cascade to consumer code. Converters are never hand-edited — they're automatically regenerated from interface declarations.

Development

task fmt           # format code
task vet           # run go vet
task generate      # regenerate converters
task lint          # lint with revive
task test          # run tests
task ci            # full local CI suite
task cli:build     # build the CLI
task mcp:build     # build MCP server for AI clients

Tests run against an in-process httptest server with 48% coverage. All exported symbols are documented with godoc.

See CLAUDE.md for development guide and MILESTONES.md for feature completion status.

Minimum Go version

Go 1.24+

Examples

See _examples/ for runnable examples:

  • translate.go — basic text translation
  • document.go — document upload/poll/download round-trip
  • glossary.go — glossary CRUD and usage

Build and run with go run -tags=ignore _examples/translate.go.

License

MIT License with Commons Clause (no commercial usage). See LICENSE file.

Personal/educational use: ✅ Free Commercial use: Requires prior permission/negotiation

For questions about commercial licensing, open an issue.

Directories

Path Synopsis
internal
apimodel
Package apimodel contains wire-format types that mirror DeepL's JSON API responses and request bodies exactly (snake_case json tags, raw string enums, etc.).
Package apimodel contains wire-format types that mirror DeepL's JSON API responses and request bodies exactly (snake_case json tags, raw string enums, etc.).
config
Package config handles persistent configuration for doopl CLI stored at ~/.doopl/config.toml.
Package config handles persistent configuration for doopl CLI stored at ~/.doopl/config.toml.
convert
Package convert holds goverter converter interface definitions.
Package convert holds goverter converter interface definitions.
interfaces
Package interfaces defines mockable interfaces for the doopl client.
Package interfaces defines mockable interfaces for the doopl client.
transport
Package transport implements the low-level HTTP plumbing shared by every DeepL API call: auth header injection, retry with exponential backoff + jitter (honoring Retry-After), and User-Agent construction.
Package transport implements the low-level HTTP plumbing shared by every DeepL API call: auth header injection, retry with exponential backoff + jitter (honoring Retry-After), and User-Agent construction.
pkg
deepl
Package deepl is an idiomatic Go client for the DeepL API (https://developers.deepl.com).
Package deepl is an idiomatic Go client for the DeepL API (https://developers.deepl.com).
model
Package model holds the public, Go-idiomatic domain types returned by the deepl.Client — as opposed to internal/apimodel, which mirrors the raw DeepL JSON wire format.
Package model holds the public, Go-idiomatic domain types returned by the deepl.Client — as opposed to internal/apimodel, which mirrors the raw DeepL JSON wire format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL