Contribution workflow 

1. Please always create an issue on Github before starting a change. This is very helpful to understand what kind of problem the pull request solves, and whether your change will be accepted.
2. Bug fixes: Please describe the nature of the bug you wish to report and provide how to reproduce the problem. We will only accept bug fixes if we can can reproduce the problem.
3. Features: Not every feature is relevant to the majority of users. In addition: We do not want to complicate the usability of this extension for a marginal feature. It helps to have a discussion about a new feature before before opening a pull request.
4. Please always create a pull request based on the updated release branch. This ensures that the necessary quality checks and tests are performed as a quality can be performed.

DeepL "Add automatic translation flag and hint" sponsored by 

• FH Aachen

Compatibility 

DeepL Translate supports:

Set up API 

Go to the extension configuration in Admin Tools > Settings > Extension Configuration.

Open the settings for deepltranslate_core and add your API key.

The correct DeepL API endpoint for free or pro plans is auto-detected by the extension and the given API key format.

Set up translation language 

1. Go to Site Management > Sites and edit your site configuration

2. Switch to tab Languages and open your target

   

3. Go to DeepL Settings and set up your Target Language (ISO Code)

   

Choice a Formality 

The formality configuration has been moved from the extension configuration to the SiteConfig languages. The Formality Select field is only displayed if the selected Target-Translate of DeepL is supported.

Note

For TYPO3 projects with more than one page root and language there is an upgrade wizard, which migrates the global formality configuration in the language config.

The same option is available in the Select field as DeepL API Supported.

Configure tables 

If not set by default, you need to define the l10n_mode for the fields you want to have translatable by deepltranslate_core.

See the tableConfiguration for details.

Detecting target language 

The following chain tries to detect the language to translate into:

1. Set up DeepL Translation language in SiteConfiguration * Target languages detected from DeepL will only appear
2. Check hreflang against DeepL supported languages * Needed for detecting EN-GB, EN-US, PT-PT or PT-BR
3. Fallback to Language ISO code

For currently allowed languages see the DeepL conform language key. As this extension retrieves available languages from the API, translations are restricted to the languages listed in the official DeepL API documentation.

If none of these match against DeepL API, translation for this language is disabled for usage within DeepL. Translation buttons and dropdowns respect this setting.

Version 4.x > 5.x 

Starting with 5.x the composer package name and extension key has been renamed!

You need to migrate the extension settings from ['TYPO3_CONF_VARS']['EXTENSIONS']['wv_deepltranslate'] to ['TYPO3_CONF_VARS']['EXTENSIONS']['deepltranslate_core'].

Then you will need to replace the previous package by uninstalling it first.

composer remove "web-vision/wv_deepltranslate"
composer require "web-vision/deepltranslate-core":"^5"

Version 3.x > 4.x 

If you are upgrading from 3.x on TYPO3 11 LTS to 12 LTS and you have used the site config setup for translations, you can simply update.

Version 2.x > 3.x 

Run the Upgrade wizard shipped with version 3. The wizard only appears, if necessary:

This wizard moves your glossaries to the new structure, fixes backend group rights and changes the module name.

After this, you have to run a GlossarySync update, either by CLI or by backend

1. sync-cli
2. glossaries

Translating content elements 

Once the extension is installed and the API key provided, we are ready to start translating content elements. When translating a content element, there are four additional options besides the normal translate and copy.

• DeepL Translate (auto detect).
• DeepL Translate.

Translating a page 

deepltranslate_core adds a separate dropdown for DeepL translation of a page to the list and web module. The dropdown is filtered to not translated pages and against DeepL API possible translation languages.

Translating a single element 

In list view, you are able to translate single elements by clicking the DeepL translate button for the language you want.

Languages that are not available will have no DeepL button. In this case, use normal translation.

My dropdown in the site configuration is empty 

This happens if TYPO3 cached the request from the DeepL API for allowed languages, but no API key was provided. In this case, empty your system cache in TYPO3. Normally no cache files should be created when no API key is provided.

If this step does not work, delete the cached files manually. The location is as follows:

• composer based installation

  var/cache/data/wvdeepltranslate

• legacy installation

  typo3temp/var/cache/data/wvdeepltranslate

After deleting the files in this directory and going to Site Configuration, the extension will reload the cache and the dropdown should have all the translatable language keys.

What will be the cost for DeepL API subscription? 

You can find all the details regarding the usage of the DeepL API here:

• https://www.deepl.com/pro-pricing.html

DeepL API Key 

Translation options not shown 

When API key is not set, deepltranslate_core disables all functions. Go to Settings and fix it. Clear cache after this.

TYPO3 Core patch required (l10n_source) 

Localizing a record whose table declares a translation source field (l10n_source) - for example content elements built with MASK - can create a duplicate translation in the same language. This is the root cause of the duplicated translations reported for web-vision/deepltranslate-auto-renew in #42.

The defect is in the TYPO3 Core, not in this extension: BackendUtility::getRecordLocalization() matches existing translations by l10n_source when the table defines one and does not fall back to l10n_parent. A valid translation created without populating l10n_source (the usual result of a plain DataHandler datamap, an importer, a migration or MASK) is not found, so DataHandler::localize() creates a second one.

The fix is upstream: forge #110281, Gerrit 94915 (13.4). TYPO3 v12.4 has reached ELTS and never receives the fix upstream. Until the fix is released for v13.4, and permanently for v12.4, instances have to apply it through a Composer patch.

This extension ships the patch file below Documentation/CorePatches/ and declares it in its own composer.json. When the project uses vaimo/composer-patches, nothing has to be configured: patch declarations are collected from installed dependencies as well, not only from the root composer.json, so having this extension installed is enough and the patch matching the TYPO3 version in use is applied automatically:

- Applying patches for typo3/cms-backend (1)
  ~ web-vision/deepltranslate-core: Documentation/CorePatches/typo3-cms-backend-110281-v12-v13.patch [NEW]

Do not declare the same patch a second time in the project. Declarations for the same target package are de-duplicated, the declaration of the dependency wins and the own one is dropped silently.

Plugins which only evaluate the root composer.json - for example cweagans/composer-patches in its default configuration - do not pick that declaration up. Copy the patch file into the project and declare it, scoped so it only applies to the affected versions:

{
    "require-dev": {
        "vaimo/composer-patches": "^6.0.1"
    },
    "extra": {
        "patches": {
            "typo3/cms-backend": {
                "TYPO3 #110281 l10n_source on v12.4 (ELTS, always)": {
                    "source": "patches/typo3-cms-backend-110281-v12-v13.patch",
                    "version": ">=12.4.0 <13.0.0"
                },
                "TYPO3 #110281 l10n_source on v13.4 (until the fix release)": {
                    "source": "patches/typo3-cms-backend-110281-v12-v13.patch",
                    "version": ">=13.4.0 <13.4.34"
                }
            }
        }
    }
}

Patches the project applies to typo3/cms-backend itself may need adoption: they have to apply on top of the changes shown below, otherwise patching fails and aborts the Composer run. The same is true for patches provided by other extensions for the same file.

See the general TYPO3 documentation on applying Composer patches for project-specific setup details. The patch used by this extension:

diff --git a/Classes/Utility/BackendUtility.php b/Classes/Utility/BackendUtility.php
index 893f781..f442596 100644
--- a/Classes/Utility/BackendUtility.php
+++ b/Classes/Utility/BackendUtility.php
@@ -27,6 +27,7 @@
 use TYPO3\CMS\Core\Database\Connection;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Database\Platform\PlatformInformation;
+use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;
 use TYPO3\CMS\Core\Database\Query\QueryBuilder;
 use TYPO3\CMS\Core\Database\Query\QueryHelper;
 use TYPO3\CMS\Core\Database\Query\Restriction\DeletedRestriction;
@@ -293,10 +294,7 @@
             $queryBuilder->select('*')
                 ->from($table)
                 ->where(
-                    $queryBuilder->expr()->eq(
-                        $tcaCtrl['translationSource'] ?? $tcaCtrl['transOrigPointerField'],
-                        $queryBuilder->createNamedParameter($uid, Connection::PARAM_INT)
-                    ),
+                    self::createTranslationParentConstraint($queryBuilder, $tcaCtrl, (int)$uid),
                     $queryBuilder->expr()->eq(
                         $tcaCtrl['languageField'],
                         $queryBuilder->createNamedParameter((int)$language, Connection::PARAM_INT)
@@ -314,6 +312,44 @@
         return $recordLocalization;
     }
 
+    /**
+     * Constraint matching all translations of the given record.
+     *
+     * `translationSource` (l10n_source) is preferred, since it is the more precise information for
+     * translation chains. It is however not maintained by all writes - a DataHandler datamap which
+     * creates a translation by only setting the language field and the transOrigPointerField leaves
+     * it empty - so such records are matched by their transOrigPointerField (l10n_parent) instead.
+     * Without that, valid translations would be invisible for callers like
+     * `DataHandler::localize()`, which uses this lookup to prevent duplicate translations.
+     *
+     * @param array $tcaCtrl The `ctrl` section of the table
+     */
+    protected static function createTranslationParentConstraint(
+        QueryBuilder $queryBuilder,
+        array $tcaCtrl,
+        int $uid
+    ): CompositeExpression|string {
+        $uidParameter = $queryBuilder->createNamedParameter($uid, Connection::PARAM_INT);
+        $translationOriginPointerConstraint = $queryBuilder->expr()->eq(
+            $tcaCtrl['transOrigPointerField'],
+            $uidParameter
+        );
+        if (!isset($tcaCtrl['translationSource'])) {
+            return $translationOriginPointerConstraint;
+        }
+
+        return $queryBuilder->expr()->or(
+            $queryBuilder->expr()->eq($tcaCtrl['translationSource'], $uidParameter),
+            $queryBuilder->expr()->and(
+                $queryBuilder->expr()->eq(
+                    $tcaCtrl['translationSource'],
+                    $queryBuilder->createNamedParameter(0, Connection::PARAM_INT)
+                ),
+                $translationOriginPointerConstraint
+            )
+        );
+    }
+
     /*******************************************
      *
      * Page tree, TCA related