Known issues 

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.

Inline markup in translated rich text 

Rich text is sent to DeepL as XML. Before it is sent, it is prepared for the way DeepL places inline markup, and the preparation is reverted in the translation: inline elements like <a>, <em> or <strong> are sent as non_splitting_tags, so a sentence is translated as a whole across its markup, links touching each other stay separate links, <sup> and <sub> stay on the word they belong to, and characters XML does not allow are removed. Processing instructions in rich text, for example the declaration <?xml version="1.0"?> of an inline SVG or <?php echo 1; ?>, are sent as placeholders and come back in their place, written with one space between target and data. If DeepL drops a placeholder, its instruction is lost. Content of unknown format holding a processing instruction but no element is plain text. Some results differ from the source on purpose or because of DeepL:

  • <?= $name ?> and <?php?> are no processing instructions to the HTML parser of the extension (masterminds/html5). It reads them as comments and repeats the character after <?, the translation holds <!--<?== $name ?>--> and <!--<?pphp?>-->.
  • Words glued to an element by mistake, like Our<strong>new</strong>offer, come back with spaces, Unser <strong>neues</strong> Angebot. The translation is new text, and readable spacing is the better result.
  • A single styled letter of a word, like i<em>Phone</em> or e<strong>Mail</strong>, has no word of its own. DeepL can move the letter into or out of the element, for example <em>iPhone</em>, or drop the element. No text is lost.
  • A link on part of a word can be lost when the translation is one word, Fahr<a>rad</a> becomes bicycle in English. The translation is kept, a warning is logged, and the editor gets a flash message naming the field and the link, so it can be added again. The message is kept in the session of the editor, so it outlives the AJAX request of the localization wizard and is shown with the next backend page. Callers of WebVisionDeepltranslateCoreServiceDeeplService::translateContent() find the lost links in WebVisionDeepltranslateCoreDomainDtoTranslateContext::getLostLinks().

The preparation adds a short reference number to every inline element of the request. Tags are not billed, but they count for the request size limit of DeepL (128 KiB). For the rich text of the development instances the request grows by about 12 %, for a paragraph dense with inline markup by about 45 %.

Content format of translated fields 

Rich text is sent to DeepL as XML and converted back, plain text is escaped before and decoded after the translation. Which way a field takes is its content format, WebVisionDeepltranslateCoreDomainEnumContentFormat, resolved from the TCA of the field by WebVisionDeepltranslateCoreServiceContentFormatResolver.

Fields of inline children 

When a record is translated, TYPO3 localizes its inline children along with it, for example the file references of a content element, and calls the DeepL hook for their fields as well. These fields are resolved in the table and the record type of the child, not in the record the translation was started for. A file reference title like Ref <title> & co is translated as plain text, and a child field named like a rich text field of the parent is not handled as rich text.

The overrideChildTca of the inline parent field applies as in the backend form, before the columnsOverrides of the record type, if the record is the inline child of exactly one parent record. A field it turns into rich text is translated as rich text, a rich text field it turns into a plain text area or a code editor is not.

In a workspace, the fields are resolved with the workspace version of the record, whose values TYPO3 passes to the hook. A content element whose CType was changed in the workspace, for example from bullets to text, is translated in the format of its new type.

Code editor fields 

HTML edited in a code editor (renderType codeEditor with the format html, the default), for example the content element "Plain HTML" (CType html), is translated like rich text. The content of <script> and <style> is sent with ignore_tags and kept byte by byte, <, && and --> included. Without it, the XML tag handling lets DeepL translate strings in them, for example var label = "Opening hours" becomes var label = "Öffnungszeiten". Attribute values such as title, aria-label or data-* are not translated, as before. The content is parsed as HTML, so it is written back in normalized form, for example <br />, quoted attributes and characters instead of named entities, and comments with -- inside are made valid XML, see "Inline markup in translated rich text" above.

On TYPO3 12 the code editor is provided by typo3/cms-t3editor. Without it, the field of "Plain HTML" is a plain textarea, and this extension declares its format html in the TCA, so it is translated the same way. The textarea the editor sees does not change.

Code in other formats, for example TypoScript, is not sent to DeepL. The translation keeps the code of the source record unchanged.

Attributes 

The attribute names and values of every element come back as written in the source. The conversion to XML dropped attribute names XML does not allow, like @click of Alpine.js, #ref of Vue or [disabled] and (click) of Angular, it lowercased names, kept only the first of duplicate attributes and escaped values like onclick="if (a < b && c) …". An element whose attributes would change is sent with a number in the attribute dlt-a, and its attribute text is taken from the source again. Other elements are sent as before. Attribute values are not translated, as before, DeepL does not translate them. Not kept are the space before >, the / of a self-closing tag and a missing end tag of <script>, which is added.

Callers without a content format 

Add-ons which call WebVisionDeepltranslateCoreServiceDeeplService::translateContent() without setting a content format get the content format Unknown. Their content is handled as plain text when it contains no tag, for example Fish & Chips or Kinder < 12, or when the HTML parser would change it, for example a<b, I </3 you, Ref <title> & co or Use <b> for bold, where the element is never closed. Any other content is handled as rich text: its result is not decoded and is returned as the HTML serializer writes it. Rich text written by the rich text editor closes every element. An & that starts no entity, like in <p>Q&A</p>, is kept by the HTML parser and does not make the content plain text, it is returned as <p>Q&amp;A</p>.

A plain text field holding markup the HTML parser keeps, for example a heading Use <b>bold</b> & more, is returned as rich text, with &amp;. Add-ons know their fields and set the content format with WebVisionDeepltranslateCoreDomainDtoTranslateContext::setContentFormat(), WebVisionDeepltranslateCoreServiceContentFormatResolver resolves it from the TCA of the field and the record.

Stored rich text 

The translated rich text is written the way TYPO3 stores it: void elements as <br />, <hr /> and <img … />, and < and > in attribute values escaped as &lt; and &gt;, unless the source writes the attributes of the element differently, see above. A raw > in a title cuts the link apart in the frontend, and an <hr> on its own line is removed when the translation is saved through the rich text transformation. Line breaks are stored as LF instead of CRLF.

Failed translations 

A field which cannot be translated keeps the text of the source language, as before. The editor now gets a warning naming the field and the record instead of an information, and the same is logged with the level warning. The warning is kept in the session of the editor like the warning about a lost link, so it is shown after the localization wizard and after a redirect as well. Both warnings name the record the field belongs to, for a file reference or another inline child localized along with its parent the child record.

TYPO3 Core patch may be 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) and released with TYPO3 v13.4.34. This extension requires at least that version on the TYPO3 v13 side, so nothing has to be done on TYPO3 v13.

TYPO3 v12.4 has reached ELTS and never receives the fix. Instances on TYPO3 v12.4 have to apply the patch themselves.

No Composer patch is declared any more 

Earlier releases declared the patch in the extra.patches section of the composer.json of this extension. That declaration used the object form with a source and a version key, which only vaimo/composer-patches understands. Patch declarations are collected from installed dependencies as well, so projects using cweagans/composer-patches aborted their Composer run with an "Array to string conversion" error (1.7.3) or a type error in ResolverBase (2.0.0). See deepltranslate-core#646.

The extension therefore no longer declares or applies any Composer patch. The patch file below Documentation/CorePatches/ stays in the repository as documentation.

Applying the patch in a project 

Copy Documentation/CorePatches/typo3-cms-backend-110281-v12-v13.patch from web-vision/deepltranslate-core into the project - for example into its patches/ directory - and declare it for typo3/cms-backend.

With cweagans/composer-patches the patch is declared as a plain path or URL string:

{
    "extra": {
        "patches": {
            "typo3/cms-backend": {
                "TYPO3 #110281 l10n_source": "patches/typo3-cms-backend-110281-v12-v13.patch"
            }
        }
    }
}
Copied!

vaimo/composer-patches additionally understands the object form, which can scope a patch to the affected TYPO3 versions:

{
    "extra": {
        "patches": {
            "typo3/cms-backend": {
                "TYPO3 #110281 l10n_source": {
                    "source": "patches/typo3-cms-backend-110281-v12-v13.patch",
                    "version": ">=12.4.0 <13.0.0"
                }
            }
        }
    }
}
Copied!

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 shipped by this extension:

typo3-cms-backend-110281-v12-v13.patch
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
Copied!