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_, 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. 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</, come back with spaces,strong>offer Unser <strong>neues</. The translation is new text, and readable spacing is the better result.strong> Angebot - A single styled letter of a word, like
i<em>Phone</orem> e<strong>Mail</, has no word of its own. DeepL can move the letter into or out of the element, for examplestrong> <em>i, or drop the element. No text is lost.Phone</ em> - A link on part of a word can be lost when the translation is one word,
Fahr<a>rad</becomesa> bicyclein 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 ofWebfind the lost links inVision Deepltranslate Core Service Deepl Service:: translate Content () Web.Vision Deepltranslate Core Domain Dto Translate Context:: get Lost Links ()
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, Web,
resolved from the TCA of the field by
Web.
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 override of the inline parent field applies as in the backend
form, before the columns 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 (render code 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_ 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- 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/. 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 . An element whose attributes
would change is sent with a number in the attribute dlt-, 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 Web
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 </, 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</, is kept by the HTML parser and does not make
the content plain text, it is returned as <p>Q&A</.
A plain text field holding markup the HTML parser keeps, for example a heading
Use <b>bold</, is returned as rich text, with &. Add-ons know
their fields and set the content format with
Web,
Web 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 < and >, 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_) - 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- in
#42.
The defect is in the TYPO3 Core, not in this extension:
Backend matches existing translations by
l10n_ when the table defines one and does not fall back to
l10n_. A valid translation created without populating l10n_
(the usual result of a plain DataHandler datamap, an importer, a migration or
MASK) is not found, so Data 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. section of the
composer. 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 Resolver (2.0.0). See
deepltranslate-core#646.
The extension therefore no longer declares or applies any Composer patch.
The patch file below Documentation/ stays in the repository as
documentation.
Applying the patch in a project
Copy Documentation/ from
web-vision/deepltranslate-core
into the project - for example into its patches/ directory - and declare it
for typo3/.
With cweagans/ 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"
}
}
}
}
vaimo/ 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"
}
}
}
}
}
Patches the project applies to typo3/ 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:
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