README

TYPO3 14 extension for DeepL V3 text and file translation in frontend content elements and backend modules.

The extension provides the product UI, TYPO3 controllers, templates and frontend access handling. DeepL HTTP communication and shared V3 approval storage are delegated to ppl/ppl-deepl-v3-requests.

Features

Frontend content element for text translation.
Frontend content element for file translation.
Backend module for text translation.
Backend module for file translation.
Backend configuration module for languages, glossaries, style rules and frontend access.
Local approval workflow for fetched DeepL languages.
Local approval workflow for fetched DeepL glossaries.
Local approval workflow for fetched DeepL V3 style rules.
Target-language filtering for glossaries and style rules.
Optional custom instructions for text translation.
Frontend access control through TYPO3/felogin login page redirects.

V3 Architecture

ppl_deepl_v3_translate is a standalone TYPO3 extension, but it does not talk to DeepL directly. The package uses the local adapter V3RequestAdapter, which calls services from ppl_deepl_v3_requests.

This keeps the translate package focused on TYPO3 behavior:

Controllers and Fluid templates.
Backend modules and frontend plugins.
Validation and language/glossary/style-rule selection.
UI access to shared approved data.
Frontend login and logout handling.

The request package owns the DeepL REST details:

API base URL.
Auth key lookup.
HTTP client calls.
DeepL V3 response handling.

Related DeepL V3 Packages

The DeepL V3 line is split into focused TYPO3 extensions:

ppl/ppl-deepl-v3-requests (ppl_deepl_v3_requests): shared request and configuration layer. It owns the DeepL API key lookup, endpoint selection, HTTP calls, language/glossary/style-rule fetches, custom instructions and shared approval storage.
ppl/ppl-deepl-v3-translate (ppl_deepl_v3_translate): this package. It provides frontend content elements and backend modules for interactive text and file translation.
ppl/ppl-deepl-v3-batch-translation (ppl_deepl_v3_batch_translation): backend workspace for translating TYPO3 page trees, pages and content elements with preflight review and controlled record writes.
ppl/ppl-deepl-v3-extension-translator (ppl_deepl_v3_extension_translator): backend audit and repair module for extension XLF files, missing translation keys and selected write actions with backups.

All V3 packages that call DeepL should go through ppl_deepl_v3_requests. Translate, Batch Translation and Extension Translator share approved languages, glossaries, style rules and custom-instruction presets through that request package.

Relationship To HDA DeepL V2

PPL DeepL V3 Translate builds on the product and workflow foundation of HDA DeepL V2 Translate. The frontend elements, backend modules, language approval flow, glossary approval flow and access configuration stay aligned where possible, but V2 and V3 remain separate TYPO3 extensions at Composer, namespace, storage and API-client level.

HDA DeepL V2 package:

Extension key: hda_deepl_v2_translate
Composer package: hda-ppl/hda-deepl-v2-translate
Namespace: HdaPpl\HdaDeeplV2Translate
DeepL access: deeplcom/deepl-php
V3 request package: not required
V3-only controls: not available
Runtime storage: var/hda_deepl_v2_translate/

V3 package:

Extension key: ppl_deepl_v3_translate
Composer package: ppl/ppl-deepl-v3-translate
Namespace: Ppl\PplDeeplV3Translate
DeepL access: ppl/ppl-deepl-v3-requests
Direct DeepL\DeepLClient usage: not used
V3-only controls: style rules and custom instructions

Historical V2 package names are intentionally not used in this release documentation. The important V3 differences are the request adapter, V3-only capabilities and separate V3 runtime storage.

Requirements

TYPO3 CMS 14
PHP 8.2 or newer
ppl/ppl-deepl-v3-requests 14
A DeepL API key with access to the used V3 features

Installation

Install the request package and the translate package:

composer require ppl/ppl-deepl-v3-requests:^14.0 ppl/ppl-deepl-v3-translate:^14.0

Run the TYPO3 extension setup if your deployment does not do it automatically:

vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

Include the shipped TypoScript setup when frontend content elements are used.

DeepL Configuration

Configure the DeepL key in the request package, not in this translate package.

TYPO3 extension configuration:

'EXTENSIONS' => [
    'ppl_deepl_v3_requests' => [
        'authKey' => 'your-deepl-auth-key',
    ],
],

Optional endpoint host settings also belong to the request package.

Do not commit API keys to the repository. This package ships no API key and no TypoScript auth-key fallback.

Backend Workflow

Open the TYPO3 backend module group PPL DeepL V3.

Configuration module:

Fetch languages from DeepL.
Approve the languages that may be used in frontend and backend selections.
Fetch glossaries from DeepL.
Approve the glossaries that may be selectable.
Fetch style rules from DeepL.
Approve style rules and use their target-language metadata for filtering.
Configure frontend access behavior.

Translation module:

Select source and target language.
Enter text.
Optionally choose an approved glossary.
Optionally choose an approved V3 style rule.
Optionally enter custom instructions.
Translate and copy the output.

File translation module:

Select source and target language.
Optionally choose an approved glossary.
Upload a supported document.
Start document translation.

Supported file upload types are TXT, PDF, DOCX and PPTX. Uploads are limited to 10 MiB per file and are checked server-side by file size, extension, MIME type and document magic bytes before a translation request is started. The limit is defined in DocumentUploadValidationService::MAX_UPLOAD_BYTES for local project changes.

Frontend Workflow

Editors can create content elements for:

DeepL V3 text translation.
DeepL V3 file translation.

The frontend UI only exposes locally approved languages, glossaries and style rules. If no API key is configured, the UI renders a missing-key state instead of triggering a remote request.

Frontend Access

The extension supports TYPO3/felogin login page redirects only. Stored legacy values such as ppl_login are normalized to login_page; allowFrontendUsers and allowBackendUsers are ignored and removed from saved extension configuration on the next frontend-access save.

TYPO3/felogin login page:

Redirects to the configured login page UID.
Sends return_url and redirect_url.
Requires the felogin plugin redirect mode Defined by GET/POST Parameters.

Custom site header login links are outside of the extension redirect flow. If they should return to the protected DeepL page, they need their own valid redirect handling.

Shared Storage

Reusable DeepL V3 metadata is stored by ppl_deepl_v3_requests inside the TYPO3 var directory:

var/ppl_deepl_v3_requests/languages.json
var/ppl_deepl_v3_requests/glossaries.json
var/ppl_deepl_v3_requests/style-rules.json
var/ppl_deepl_v3_requests/custom-instructions.json

Existing files from var/ppl_deepl_v3_translate/ are migrated by the request services on first read. New writes go to the request package storage path. These files are runtime data and should not be committed to package repositories.

Security Notes

Do not commit DeepL API keys.
Do not expose backend-only modules to unauthenticated users.
Frontend access is delegated to TYPO3/felogin. This package no longer performs direct frontend-user or backend-user password checks and no longer sets a PPL frontend-login cookie.
Backend POST actions use TYPO3 FormProtection tokens for configuration saves, approval writes, backend text translation and backend file translation.
File uploads are checked by size, extension, MIME type and magic bytes. Failed validation stops before a DeepL document translation request.
Translated files are still written below fileadmin/user_upload/translated/ for download in this release line. That path is publicly reachable in typical TYPO3 webroots, so private signed downloads remain an open hardening task.
The translate package does not directly depend on deeplcom/deepl-php.
The translate package expects all V3 HTTP behavior to go through ppl_deepl_v3_requests.

Release Line

Version 14.x is the TYPO3 14 release line; see the official TYPO3 system requirements.

License

This extension is released under the GNU General Public License v2.0 or later, aligned with HDA DeepL V2 Translate and the common TYPO3 extension license. See LICENSE.

ppl / ppl-deepl-v3-translate

Maintainers

Package info

Statistics

Security