DeepL PHP Client Library

In the v3 API, glossaries are no longer limited to a single language pair. Instead, they use the concept of glossary dictionaries.

• Monolingual Glossaries (v2): A single GlossaryInfo object containing one SourceLanguageCode and one TargetLanguageCode.
• Multilingual Glossaries (v3): A MultilingualGlossaryInfo object that contains an array of MultilingualGlossaryDictionaryInfo objects. Each dictionary within the glossary specifies its own SourceLang, TargetLang, and its own set of entries.

To create or manage these, you use MultilingualGlossaryDictionaryEntries to encapsulate a specific language pair and its corresponding entries.

// Creating a dictionary for a specific language pair
$entries = GlossaryEntries::fromEntries(['artist' => 'Maler', 'prize' => 'Gewinn']);
$myGlossaryDict = new MultilingualGlossaryDictionaryEntries('en', 'de', $entries);

// Adding it to a multilingual glossary
$myGlossary = $deeplClient->createMultilingualGlossary('My glossary', [$myGlossaryDict]);

Export a translation memory to a TMX file using exportTranslationMemoryToFilepath(). This method creates the export job and waits for it to finish before writing the file.

$job = $deeplClient->exportTranslationMemoryToFilepath('YOUR_TM_ID', '/path/to/exported.tmx');

Alternatively, you can manage the steps manually:

1. createTranslationMemoryExport(): Starts the export. If the translation memory hasn't changed, the response may indicate reusedExisting is true.
2. waitUntilTranslationMemoryJobDone(): Waits for the job to complete.
3. downloadTranslationMemoryExport(): Writes the exported file to the specified path.

// High-level
$job = $deeplClient->exportTranslationMemoryToFilepath('YOUR_TM_ID', '/path/to/exported.tmx');

// Manual steps
$created = $deeplClient->createTranslationMemoryExport('YOUR_TM_ID');
$job = $deeplClient->waitUntilTranslationMemoryJobDone($created->jobId);
$deeplClient->downloadTranslationMemoryExport($job, '/path/to/exported.tmx');

You can apply a stored glossary to translations by providing the glossary option in the options array. When using a glossary, you must specify the sourceLang argument.

Supported for:

• translateText()
• translateDocument()
• translateDocumentUpload()

To apply multiple glossaries (up to 5) in a single request, use the glossary_ids option instead of glossary. This must be an array of glossary IDs, GlossaryInfo, or MultilingualGlossaryInfo objects. glossary_ids cannot be combined with the singular glossary option.

// Using a single glossary
$withGlossary = $deeplClient->translateText($text, 'en', 'de', ['glossary' => $myGlossary]);

// Using multiple glossaries (up to 5)
$deeplClient->translateText(
    $text, 'en', 'de', ['glossary_ids' => [$glossaryA, $glossaryB]]
);

// Using a glossary for document translation
$deeplClient->translateDocument(
    $inFile, $outFile, 'en', 'de', ['glossary' => $myGlossary]
);

You can import a TMX file as a new translation memory using two different approaches:

1. High-level approach

Use importTranslationMemoryFromFilepath() to handle the entire process: creating the job, uploading the file, and waiting for completion. It returns a TranslationMemoryJob containing the new translationMemoryId.

$job = $deeplClient->importTranslationMemoryFromFilepath('/path/to/legal.tmx', 'Legal TM', 300);
echo "Created translation memory {$job->result()->translationMemoryId}\n";

2. Step-by-step approach

If you need to upload the file yourself or poll for progress manually, use the granular methods:

1. createTranslationMemoryImport(): Returns an upload URL and a job ID. The job status will be awaiting_input until the file is uploaded.
2. uploadTranslationMemoryFile(): Uploads the file content to the provided URL.
3. waitUntilTranslationMemoryJobDone(): Polls the job status until completion.

Note: The upload URL is a pre-signed storage URL outside the DeepL API; your authentication key is not sent to it.

// High-level
$job = $deeplClient->importTranslationMemoryFromFilepath('/path/to/legal.tmx', 'Legal TM', 300);

// Step-by-step
$fileContent = file_get_contents('/path/to/legal.tmx');
$created = $deeplClient->createTranslationMemoryImport('legal.tmx', strlen($fileContent), null, 'Legal TM');
$deeplClient->uploadTranslationMemoryFile($created, $fileContent);
$job = $deeplClient->waitUntilTranslationMemoryJobDone($created->jobId, 300);

Multilingual glossaries (v3 API) allow you to define custom terms for specific language pairs.

Using GlossaryEntries

Create entries using GlossaryEntries::fromEntries() with an associative array where keys are source terms and values are target terms.

Creating from objects

1. Create GlossaryEntries.
2. Wrap them in a MultilingualGlossaryDictionaryEntries object specifying the source and target languages.
3. Pass an array of these dictionary objects to createMultilingualGlossary().

$entries = GlossaryEntries::fromEntries(['artist' => 'Maler', 'prize' => 'Gewinn']);
$myGlossaryDict = new MultilingualGlossaryDictionaryEntries('en', 'de', $entries);
$myGlossary = $deeplClient->createMultilingualGlossary('My glossary', [$myGlossaryDict]);

Creating from CSV

Use createMultilingualGlossaryFromCsv() to upload a glossary from a CSV string.

$csvData = file_get_contents('/path/to/glossary_file.csv');
$myCsvGlossary = $deeplClient->createMultilingualGlossaryFromCsv(
    'CSV glossary',
    'en',
    'de',
    $csvData,
);

// Create an English to German glossary with two terms:
$entries = GlossaryEntries::fromEntries(['artist' => 'Maler', 'prize' => 'Gewinn']);
$myGlossaryDict = new MultilingualGlossaryDictionaryEntries('en', 'de', $entries);
$myGlossary = $deeplClient->createMultilingualGlossary('My glossary', [$myGlossaryDict]);

Style rules allow you to customize translations with managed, shared rules for style and formatting.

Core Operations:

• Create: createStyleRule($name, $language, $configuredRules = [], $customInstructions = []).
• Retrieve: getStyleRule($idOrObject).
• List: getAllStyleRules(page: 0, pageSize: 10, detailed: false).
• Update: updateStyleRuleName($styleRule, $newName) and updateStyleRuleConfiguredRules($styleRule, $rules).
• Delete: deleteStyleRule($styleRule).

Custom Instructions: You can manage free-text prompts within a rule using createStyleRuleCustomInstruction(), getStyleRuleCustomInstruction(), updateStyleRuleCustomInstruction(), and deleteStyleRuleCustomInstruction().

Using Style Rules: Pass the style_id option (containing an ID or StyleRuleInfo object) to translateText() or translateDocument().

// Create a rule with custom instructions
$styleRule = $deeplClient->createStyleRule(
    'Formal English',
    'en',
    ['style_and_tone' => ['formal_informal' => 'formal']],
    [['label' => 'Formality', 'prompt' => 'Always use formal language']]
);

// Use the rule in translation
$result = $deeplClient->translateText(
    'Hello, world!',
    'en',
    'de',
    ['style_id' => $styleRule]
);