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.

Contribution information 

Build/Scripts/runTests.sh -s renderDocumentation

xdg-open Documentation-GENERATED-temp/Index.html

Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s functional -d sqlite && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s functional -d mariadb -i 10.7

Build/Scripts/runTests.sh -t 14 -p 8.5 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.5 -s functional -d sqlite && \
Build/Scripts/runTests.sh -t 14 -p 8.5 -s functional -d mariadb -i 10.7

Build/Scripts/runTests.sh -t 13 -p 8.5 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.5 -s unit && \
Build/Scripts/runTests.sh -t 13 -p 8.5 -s unitRandom

Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s unit && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s unitRandom

Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s cgl

Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s phpstan && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s phpstan

Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 13 -p 8.2 -s phpstanGenerateBaseline && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate && \
Build/Scripts/runTests.sh -t 14 -p 8.2 -s phpstanGenerateBaseline

DeepL "Add automatic translation flag and hint" sponsored by 

• FH Aachen

Composer mode 

composer require -W \
   'web-vision/deepltranslate-core':'~6.0.0@dev'

composer require \
    'web-vision/deeplcom-deepl-php':'~1.18.0@dev' \
    'web-vision/deepl-base':'~2.0.0@dev' \
    'web-vision/deepltranslate-core':'~6.0.0@dev'

Classic mode 

Extension Configuration - API Key 

This extension uses the DeepL under the hood to provide the translations, which requires a API key regarding the plan and connected limits. Get your key here and enter it to the extension configuration for deepltranslate_core.

Further reading 

• Global extension configuration

Translate Page with or without contents elements 

deepltranslate-core respects the new translation workflow and shares the same wizard provided by TYPO3 v14, which means that translating a page and optional directly the contents are started using the generic translation dropdown.

1. Generic translation dropdown to create translation

   

2. Select content elements to translate

   

3. Select Translate localization mode

   

   Note

   DeepL based translation is only available for Translate localization mode and will not be available if Copy localization mode is selected here.

4. Select Translate with DeepL localization handler

   

5. Review and confirm selected localization options

   

6. Localization is in progress

   

7. Localization completed successfully

   

Translate 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.

1. Start translate of missing records for language

   

2. Select source language

   

3. Select content elements to translate

   

4. Select Translate localization mode

   

5. Select Translate with DeepL localization handler

   

6. Review and confirm selected localization options

   

7. Localization is in progress

   

8. Localization completed successfully

   

Translate Record 

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

1. Start localization for a record with Localize to in the Records Module

   

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 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.

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.

Compatibility 

DeepL Translate (CORE) supports:

Set up API 

1. Go to the extension configuration in System > Settings > Extension Configuration.

   Note

   In TYPO3 v13 the path is AdminTools > Settings > Extension Configuration.

2. Open the settings for deepltranslate_core > Settings and add your API key.

   

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

Further Readings

• Global extension configuration

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.

composer-mode 

composer config minimum-stability "dev" \
&& composer config "prefer-stable" true \
composer require -W \
   "web-vision/deepltranslate-core":"6.0.*@dev"

classic-mode 

1. Get it from the Extension Manager: Switch to the module System > Extensions. Switch to Get Extensions and search for the extension key deepltranslate_core and import the extension from the repository.
2. Get it from typo3.org: You can always get current version from TER by downloading the zip version. Upload the file afterwards in the Extension Manager.
3. Get it from GitHub release: TER upload archives are added to the corresponding GitHub release page, in case you need to download or update the extension and GITHUB_RELEASES is down or not reachable.

composer-mode 

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

classic-mode 

1. Uninstall "wv_deepltranslate" using the Extension Manager. Switch to the module Admin Tools > Extensions and filter for wv_deepltranslate and remove (uninstall) the extension.

2. Ensure to remove the folder completely. Run

   rm -rf typo3conf/ext/wv_deepltranslate

   Copied!
3. Get it from the Extension Manager: Switch to the module Admin Tools > Extensions. Switch to Get Extensions and search for the extension key deepltranslate_core and import the extension from the repository.
4. Get it from typo3.org: You can always get current version from TER by downloading the zip version. Upload the file afterwards in the Extension Manager.

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:

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

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.

Settings 

Tab Settings provides basic extension settings required for minimal operational state.

API 

Tab API provides the ability to set default settings used for DeepL API. requests.

Official Addons 

Following official addons are available:

Also available 

Breaking Changes 

Features 

Deprecation 

Important 

Description 

The autotranslate mode has been removed now because it literally was only a duplicate of the normal translate mode and was not handled differently.

Not having a use-case and a real difference possible at the moment the mode is removed before re-implementing it for TYPO3 v14 again having no value.

In case a valid use-case and different handling purpose may raise up in the future it will be (re-)added as a feature again.

Impact 

Except not having it selectable anymore there is no impact because it was the same process as the casual deepl based translate mode.

Affected installations 

Instances upgrading from deepltranslate-core 5.x or earlier will notice that the mode has been dropped. It's simple not selectable anymore.

Migration 

There is no migration path. Developers can use the events to introduce a custom mode again and handle it on their own if they really want or have a change not provided upstream to make use of this mode.

Otherwise simple use the remaining deepl base translate mode and having the same outcome.

Description 

The DeeplTranslateViewHelper has been marked as deprecated in 5.x and is no longer used within the deepltranslate extension ecosystem and is now removed without any replacement.

Following class is removed:

• \WebVision\Deepltranslate\Core\ViewHelpers\DeeplTranslateViewHelper

Impact 

Error is thrown that ViewHelper cannot be found when used in custom extension or project fluid templates.

Affected installations 

Instances using the ViewHelper in project or extension fluid templates.

Migration 

There is no direct replacement for the ViewHelper and extension or project needs to implement their own implementation, for example by cloning the removed ViewHelper into a local path extension.

Own usage has been replaced for TYPO3 v13 the depending EXT:deepl_base overrides the templates and using a ViewHelper which dispatches the PSR-14 \WebVision\Deepl\Base\Event\ViewHelpers\ModifyInjectVariablesViewHelperEvent, which is not needed in TYPO3 v14 because of the completely overhaul of the translation (localization) behaviour.

Description 

Support for TYPO3 v12 has been removed for 6.x based on our dual TYPO3 core version support per major version as casual support matrix.

This includes removing code paths and configurations only required for TYPO3 v12.

Impact 

TYPO3 v12 or older instances cannot update to the 6.x version and are required to upgrade TYPO3 to be able to install the next version of the EXT:deepltranslate_core and related extensions/addons based on this version.

Extension cannot be installed in that version but does not break otherwise.

Affected installations 

TYPO3 v12 or older instances with web-vision/deepltranslate-core version 5.x.

Migration 

Upgrade TYPO3 to supported version for 6.x beforehand or in the same step.

Description 

TYPO3 v14.3.* has been added coming with following changes:

Impact 

web-vision/deepltranslate-core can now be installed and used in TYPO3 v14.3 instances.

Supported features are completely available for TYPO3 v13 and v14, except that generic TYPO3 handling is used provided by these versions.

Description 

EXT:deepltranslate_core provides the \AccessItemInterface to define access subtypes to use as Custom Permission Options grouped as deepltranslate.

These items are now automatically registered through the Symfony Dependency Injection container by simply providing autoconfigured classes implementing \AccessItemInterface.

No manual registration required anymore.

<?php

namespace MyVendor\MyExt\Access;

use WebVision\Deepltranslate\Core\Access\AccessItemInterface;

final class CustomAccess implements AccessItemInterface
{
    public function getIdentifier(): string
    {
        return 'customAccess';
    }

    public function getTitle(): string
    {
        return sprintf(
            '%s:%s',
            'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf',
            'be_groups.deepltranslate_access.items.customAccess.title',
        );
    }

    public function getDescription(): string
    {
        return sprintf(
            '%s:%s',
            'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf',
            'be_groups.deepltranslate_access.items.customAccess.description',
        );
    }

    public function getIconIdentifier(): string
    {
        return 'custom-access-logo';
    }
}

Impact 

Classes implementing \AccessItemInterface defined in extensions are now automatically registered and possible provide any access items which have not been registered manually before.

This can be mitigated by using #[Exclude] attribute on the class or exclude it from the autoconfigure load configuration in Configuration/Services.yaml.

Description 

Following \WebVision\Deepltranslate\Core\Access\AccessRegistry methods has been deprecated:

• addAccess() because access items are gathered based on the \AccessItemInterface and added through the constructor by the DI container. Calling this method does not add anything and emits now a E_USER_DEPRECATED error.
• getAllAccess() is now deprecated and triggers a E_USER_DEPRECATED error. Use getItems() instead.
• getAccess() is now deprecated and triggers a E_USER_DEPRECATED error. Use get() instead.
• hasAccess() is now deprecated and triggers a E_USER_DEPRECATED error. Use has() instead.

Impact 

Calling deprecated \WebVision\Deepltranslate\Core\Access\AccessRegistry methods triggers a E_USER_DEPRECATED error.

Affected installations 

All installations that call one of the deprecated \WebVision\Deepltranslate\Core\Access\AccessRegistry methods triggers a E_USER_DEPRECATED error. Use the above mentioned replacements or remove the addAccess() calls in ext_localconf.php.

Migration 

<?php

use TYPO3\CMS\Core\Utility\GeneralUtility;
use WebVision\Deepltranslate\Core\Access\AccessRegistry;

$accessRegistry = GeneralUtility::makeInstance(AccessRegistry::class);
$accessRegistry->addAccess(new CustomAccessItem());

<?php

use TYPO3\CMS\Core\Utility\GeneralUtility;
use WebVision\Deepltranslate\Core\Access\AccessRegistry;
use WebVision\Deepltranslate\Core\TranslatorInterface;

// @todo web-vision/deepltranslate-core:>=6.0.0 Remove complete condition
//       block once lowest supported deepltranslate-core extension version
//       has been raised to 6.0.0 or higher.
if (class_exists(TranslatorInterface::class) === false) {
    $accessRegistry = GeneralUtility::makeInstance(AccessRegistry::class);
    $accessRegistry->addAccess(new CustomAccessItem());
}

 <?php

 namespace MyVendor\MyExt;

 final class SomeClass {
     public function __construct(
         private AccessRegistry $accessRegistry,
     ) {}

     public function someMethod(): void
     {
-       $allRegisteredAccessItems = $this->accessRegistry->getAllAccess();
+       // `getItems()` returns now the identifiers as keys and `array_values()`
+       // ensures to deal only with the items like with previous `getAllAccess()`.
+       $allRegisteredAccessItems = array_values($this->accessRegistry->getItems());

         foreach($allRegisteredAccessItems as $accessItem) {
             // ... do something with the access item
         }
     }
 }

 <?php

 namespace MyVendor\MyExt;

 final class SomeClass {
     public function __construct(
         private AccessRegistry $accessRegistry,
     ) {}

     public function hasAccess(): bool
     {
        $accessIdentifier = '';
-       if (!$this->accessRegistry->hasAccess($accessIdentifier)) {
+       if (!$this->accessRegistry->has($accessIdentifier)) {
          // access does not exists, take this as allowed.
          return true;
        }

-       $accessItem = $this->accessRegistry->getAccess($accessIdentifier);
+       $accessItem = $this->accessRegistry->get($accessIdentifier);
        return $this->getBackendUserAuthentication()->check(
            'custom_options',
            sprintf('deepltranslate:%s', $accessItem->getIdentifier()),
        );
     }

     private function getBackendUserAuthentication(): BackendUserAuthentication
     {
         return $GLOBALS['BE_USER'];
     }
 }

Breaking Changes 

Features 

Deprecations 

Important notes