> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# Building a Document Translator with the DeepL API

> Streamline document localization workflows with automated translation for businesses and developers

## Why Build a Document Translator?

In today's global business environment, organizations frequently need to translate various document types - from technical manuals and legal contracts to marketing materials and internal communications. Manually uploading files to web-based translation services can be time-consuming and inefficient, especially when dealing with multiple documents.

By building a command-line Java application with the DeepL API, you can automate document translation processes, integrate them into CI/CD pipelines, and provide a reliable solution for bulk document processing. This approach is particularly valuable for:

* **Development teams** who need to localize documentation and user manuals
* **Content teams** managing multilingual marketing materials
* **Businesses** requiring regular translation of contracts, reports, and communications
* **Automation workflows** where translation needs to be triggered programmatically

## Setting Up Your Document Translator

### Prerequisites

Before you begin, you'll need:

* Java Development Kit (JDK) 8 or higher
* Apache Maven for dependency management
* A DeepL API key (get one at [DeepL API](https://www.deepl.com/pro-api))
* Basic familiarity with Java and command-line tools

### Project Overview

Our Java application leverages the official DeepL Java SDK to translate documents across multiple formats. It provides a simple command-line interface that takes an input file and target language, automatically generating appropriately named output files.

Here's the complete implementation breakdown:

#### 1. Project Setup and Dependencies

First, let's set up the Maven project structure with the necessary dependencies:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>java-document-translator</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.deepl.api</groupId>
            <artifactId>deepl-java</artifactId>
            <version>1.10.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <mainClass>App</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
```

The `deepl-java` dependency provides all the necessary functionality for interacting with the DeepL API, including document translation capabilities.

#### 2. Supported File Types Definition

We start by defining the supported file formats to provide clear feedback to users:

```java theme={null}
private static final Map<String, String> SUPPORTED_EXTENSIONS;

static {
    Map<String, String> map = new HashMap<>();
    map.put("docx", "Microsoft Word Document");
    map.put("doc", "Microsoft Word Document");
    map.put("pptx", "Microsoft PowerPoint Document");
    map.put("xlsx", "Microsoft Excel Document");
    map.put("pdf", "Portable Document Format");
    map.put("htm", "HTML Document");
    map.put("html", "HTML Document");
    map.put("txt", "Plain Text Document");
    map.put("xlf", "XLIFF Document (1.2 / 2.0 / 2.1)");
    map.put("xliff", "XLIFF Document (1.2 / 2.0 / 2.1)");
    map.put("srt", "SubRip Subtitle file");
    map.put("idml", "Adobe InDesign Markup Language");
    map.put("xml", "XML Document");
    map.put("json", "JSON Document");
    map.put("dita", "DITA topic");
    map.put("mif", "Adobe FrameMaker Interchange Format");
    SUPPORTED_EXTENSIONS = Collections.unmodifiableMap(map);
}
```

This static initialization ensures our application can quickly validate file types before attempting translation, providing immediate feedback for unsupported formats.

#### 3. Command Line Argument Processing

The application expects two command-line arguments: the input file path and target language code. The source language is automatically detected by the DeepL API.

```java theme={null}
public static void main(String[] args) {
    String inputFilePath = args[0];
    String targetLang = args[1];
    
    // Validate file extension
    String extension = "";
    int i = inputFilePath.lastIndexOf('.');
    if (i > 0 && i < inputFilePath.length() - 1) {
        extension = inputFilePath.substring(i + 1);
        String lowerCaseExtension = extension.toLowerCase();
        if (SUPPORTED_EXTENSIONS.containsKey(lowerCaseExtension)) {
            System.out.println("File type: " + SUPPORTED_EXTENSIONS.get(lowerCaseExtension));
        } else {
            System.err.println("Error: Unsupported file extension '" + extension + "'");
            return;
        }
    }
}
```

#### 4. Output File Path Generation

One key feature is automatic output file naming, which prevents accidental overwrites and clearly identifies translated versions:

```java theme={null}
// Auto-generate output file path
Path inputPathObject = Paths.get(inputFilePath);
String originalFileName = inputPathObject.getFileName().toString();
String newFileName = targetLang.toUpperCase() + "_" + originalFileName;
Path outputFilePathObject = inputPathObject.resolveSibling(newFileName);
String outputFilePath = outputFilePathObject.toString();
```

This approach transforms `document.pdf` with target language `DE` into `DE_document.pdf`, making it easy to identify translated versions.

#### 5. DeepL API Integration

The core translation functionality uses the DeepL Java SDK:

```java theme={null}
// Initialize DeepL client
String authKey = System.getenv("DEEPL_AUTH_KEY");
if (authKey == null || authKey.isEmpty()) {
    System.err.println("Error: DEEPL_AUTH_KEY environment variable not set.");
    return;
}

File inputFile = Paths.get(inputFilePath).toFile();
File outputFile = Paths.get(outputFilePath).toFile();
DeepLClient client = new DeepLClient(authKey);

// Perform translation
DocumentStatus status = client.translateDocument(inputFile, outputFile, null, targetLang);
System.out.println("Document translation initiated. Document ID: " + status.getDocumentId());
```

#### 6. Translation Status Monitoring

Document translation is asynchronous, so we need to monitor the process:

```java theme={null}
System.out.println("Waiting for translation to complete...");

while (true) {
    StatusCode statusCode = status.getStatus();
    if (statusCode == StatusCode.Done) {
        System.out.println("Translation completed successfully.");
        break;
    }
    if (statusCode == StatusCode.Error) {
        System.err.println("Error during translation: " + status.getErrorMessage());
        break;
    }
    
    Thread.sleep(1000); // Wait 1 second before checking status again
}
```

This polling mechanism ensures the application waits for translation completion and provides appropriate feedback.

### Building and Running

1. **Set up your environment:**

```bash theme={null}
export DEEPL_AUTH_KEY="your_deepl_api_key_here"
```

2. **Build the project:**

```bash theme={null}
mvn compile
```

3. **Run translations:**

Here are some practical examples of using the translator:

**Translating Technical Documentation:**

```bash theme={null}
mvn exec:java -Dexec.args="./api-documentation.pdf EN-US"
```

**Localizing Marketing Materials:**

```bash theme={null}
mvn exec:java -Dexec.args="./brochure.docx JA"
```

**Processing Subtitle Files:**

```bash theme={null}
mvn exec:java -Dexec.args="./movie-subtitles.srt DE"
```

### Wrapping Up

This Java document translator provides a solid foundation for automating document localization workflows. By combining the reliability of Java with DeepL's translation quality, you can build scalable solutions for various business needs.

The command-line interface makes it easy to integrate into existing automation scripts, CI/CD pipelines, or batch processing workflows. Whether you're a developer localizing documentation or a business automating multilingual content creation, this approach offers a practical solution for programmatic document translation.

The extensible design allows for easy customization and enhancement, making it adaptable to specific organizational requirements while maintaining the core functionality of reliable, high-quality document translation.

## References

* [DeepL API Documentation](https://developers.deepl.com/docs)
* [DeepL Java SDK](https://github.com/DeepL/deepl-java)
* [Maven Exec Plugin](https://www.mojohaus.org/exec-maven-plugin/)
* [DeepL Supported Languages](https://www.deepl.com/docs-api/translate-text/target-language/)