Planning and performing automatic translations in TYPO3 with DeepL

We integrated DeepL extensions into a TYPO3 project to automatically generate translated content. Today, I will share our experiences with DeepL. I will also take this opportunity to describe the entire organizational process.

All content in the TYPO3 installation was in English and has now been translated into German for the first time. Additional languages will be added to the project in the future.

We need to define the language precisely before we can set it up technically. Portuguese, for example, is also the official language of Brazil. However, there are many differences in Brazilian Portuguese, both in colloquial language and in technical terms.

Therefore, it matters whether the country code is configured as pt_PT (Portuguese) or pt_BR (Brazilian Portuguese).

Technical terms must always be translated consistently. Product names, on the other hand, may not need to be translated into the target language. In all cases, DeepL's glossary feature can help you maintain the correct terminology.

The free add-on "deepltranslate-glossary" is available for TYPO3, and we strongly recommend using it. It allows glossary entries to be created as a record in TYPO3 and synchronized with DeepL. DeepL will then use the glossary for all translations.

Your client should therefore create a glossary in advance, including the most important technical terms and further preferred translations. You or your client will then add these terms to TYPO3 before the translation process begins. Further glossary entries can be added at any time if they prove necessary in the course of the work.

The responsibilities and the specific translation process are also discussed with the client before work begins: Which pages should be translated first? Who is responsible for the legal documents, such as the data privacy policy?

The free version of the DeepL API only includes one glossary. This may sound sufficient if you are only planning to use one new target language, but it is not:

• Each TYPO3 installation is assigned a different glossary ID (production, staging, development or review environments, etc.).
• Also, each language in TYPO3 creates additional glossaries in DeepL. For English, German, and Spanish, you already get four glossaries (en => es, en => de, de => es, es => de), because translated content can also be selected as the source language for further translations.

Depending on the amount of text on your website, you may also reach the monthly character limit of the free plan. This can happen especially when you are initially setting up the new language version with some trial runs.

Which means you will need a Pro account for the API. You will have to discuss the fees with your client: www.deepl.com/en/pro-api#api-pricing

This question does not need to be addressed at the beginning, but your client should be aware of this option: What should happen to existing translations when the content in the original language is updated?

Using the paid add-on “deepltranslate-auto-renew,” it is possible to automatically update existing translations with DeepL in this case.
However, it should be noted that all corrections and improvements made by an editor in the translation will, of course, be overwritten.

Therefore, it is important to consider whether auto-renewal is the right choice for your project. It is technically possible to enable or disable this option for each target language.

Translations are not limited to pages and content that editors can maintain. The website template must also be configured for multiple languages (in TYPO3 primarily using XLIFF language files): buttons and labels for the search function are defined there, as are accessibility-related labels.
Other components must also be taken into account.

We have created a checklist for new languages that includes the following steps:

• Configuration of the language in the Site Configuration
• Solr Core for the search index of the new language
• Translation of the frontend labels in locallang.xlf
• Additional translations in TypoScript (_LOCAL_LANG), if needed
• Translation of contact forms and associated email templates
• Translation of cookie consent
• Creation of the specified terms in the DeepL glossary

Special attention must be paid to any legal contents, from cookie consent to the data privacy policy. Ideally, the client's legal department or a qualified person can provide a complete, legally compliant translation. Alternatively, they can perform a careful review of an automatically translated version.

This section is intended for TYPO3 integrators and developers. Those of you who are project managers may skip to the next section without a guilty conscience.

The following TYPO3 extensions are available for installation:

The documentation describes the necessary steps: https://docs.typo3.org/p/web-vision/deepltranslate-core/5.1/en-us/Administration/Configuration/Index.html

As described in the documentation, the DeepL extension supports backend fields of type "Input" and "Text" (including rich text). A requirement is that the fields are configured with 'l10n_mode' => 'prefixLangTitle'. You may need to adjust this using TCA overrides. Otherwise, the contents of the field will not be translated.

$GLOBALS['TCA']['tx_news_domain_model_news']['columns']['teaser']['l10n_mode'] = 'prefixLangTitle';
$GLOBALS['TCA']['tx_news_domain_model_news']['columns']['bodytext']['l10n_mode'] = 'prefixLangTitle';
$GLOBALS['TCA']['tx_news_domain_model_news']['columns']['description']['l10n_mode'] = 'prefixLangTitle';
$GLOBALS['TCA']['tx_news_domain_model_news']['columns']['alternative_title']['l10n_mode'] = 'prefixLangTitle';

It makes sense: as long as the translated version of the website is still in development, we probably don't want to reveal it to visitors yet. So no matter how you implement your navigation in TYPO3, make sure that the new language cannot be selected there until everything's ready.

This might be less obvious: TYPO3 automatically adds tags to the source code if a page is available in other languages.

<link rel="alternate" hreflang="en-US" href="https://www.example.org/about-us/">
<link rel="alternate" hreflang="de-de" href="https://www.example.org/de/ueber-uns/">
<link rel="alternate" hreflang="x-default" href="https://www.example.org/about-us/">

These tags let Google know when you create translations. And then the translated pages appear in search results faster than you can say "noindex".

We have therefore added a small event listener to the site package, which can be used to omit the required languages from the generation of hreflang tags.

<?php

declare(strict_types=1);

namespace Mfd\MySitepackage\EventListener;

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Frontend\Event\ModifyHrefLangTagsEvent;

/**
 * Filter/remove certain languages from the generated hreflang tags.
 * Used to prevent publishing page translations while a new frontend language is still set up.
 */
#[AsEventListener(
    identifier: 'my-sitepackage/hreflang-tag-filter',
    after: 'typo3-seo/hreflangGenerator',
)]
final readonly class HrefLangTagFilter
{
    public function __invoke(ModifyHrefLangTagsEvent $event): void
    {
        $defaultLanguages = [
            'en-US',
            'x-default'
        ];
        $disabledLanguages = [
            'de-DE',
            'fr-FR'
        ];

        $hrefLangs = $event->getHrefLangs();

        // Remove unwanted language codes from array:
        $filteredHrefLangs = array_diff_key($hrefLangs, array_flip($disabledLanguages));

        // Check if the remaining languages are only the default.
        // In that case, no hreflang tags should be rendered.
        $remainingKeys = array_keys($filteredHrefLangs);
        sort($remainingKeys);
        sort($defaultLanguages);
        if ($remainingKeys === $defaultLanguages) {
            $filteredHrefLangs = [];
        }

        $event->setHrefLangs($filteredHrefLangs);
    }
}

Once the new language version of the website is ready, you can remove the language from the event listener. So make sure to add this to your checklist.

We recommend starting with a number of selected pages that the client considers particularly important. Preferably, these should also contain some glossary terms. Have the translations reviewed by your editors. Where necessary, expand the glossary. Then proceed to the next series of pages.

By translating content step by step, you can identify problems early on and avoid them on subsequent pages.

News (and other plugin records) are stored in a central folder and then referenced on different pages. It makes sense to translate this content into its folders at an early stage. It ensures that the translations are already available when you translate the corresponding pages. Otherwise, a news plugin translated into German will still display the English originals in the frontend.

German is a language in which terms quickly grow long. I am not referring to oddities like the former "Grundstücks­verkehrs­genehmigungs­zuständigkeits­übertragungs­verordnung" (Regulation on the delegation of authority concerning land conveyance permissions).
Even the translation of “product portfolio” (7 + 9 characters) to “Produktportfolio” (16 characters without spaces) can lead to different line breaks. Or to layout problems in narrow teaser boxes.

In such cases, it is beneficial to have the option to set soft hyphens for conditional line breaks in the text field. However, this is an editorial adjustment that must be performed manually during the final review.

The shorter the original text, the more scope for interpretation DeepL has when translating it. Many terms can be translated in different ways, leading to very different meanings. This can quickly lead to incorrect or even absurd results.

• "Quality policy" (meaning a guideline) becomes "Qualitätspolitik" (Quality politics)
• "Light is the new green", a reference to environmentally friendly lightweight vehicle wheels, becomes "Licht ist das neue Grün" (meaning illumination)
• "[Client name] on the road" (on travel) becomes "[Kundenname] auf der Straße" (in the street)

DeepL tends to translate terms literally rather than according to their meaning.

Occasionally, using the DeepL buttons returns no translated text. The target language records will then contain the unchanged original text.

In such cases, clicking the “Synchronize glossaries” button and then restarting the translation process has always helped.

Experience shows that no matter how thoroughly your client works on their website, when translating, they will always find content that is outdated or needs to be revised. This can delay the translation process, at the very least.

I myself have been using DeepL for years, both professionally and personally, primarily for translations from German to English. And yet I never use the initial result. I adjust sentences and phrasing according to my personal preference and occasionally correct grammar. Sometimes I have translations rechecked by Grammarly.
Fun fact: this is precisely how I created the English version of this article.

Can I recommend automated translations in TYPO3? Yes, absolutely. It makes work much easier and saves time.
But does it have to be a fully automated solution, or should editors check every translation afterwards? You'll need to answer this question together with your client for each project.