---
title: "Configuration"
manual: "DeepL Translate (CORE)"
version: "main"
permalink: "https://docs.typo3.org/permalink/web-vision/deepltranslate-core:administrationconfiguration@main"
source: "Administration/Configuration/Index.rst"
rendered: "2026-10-06T14:40:53+00:00"
---

# Configuration {#administrationconfiguration}

## Set up API {#adminconfigurationsetupapi}

> [!WARNING]
> **Attention**
>
> Before using the DeepL API, you need to get an API key from your [DeepL Profile](https://www.deepl.com/en/your-account/keys).

1.  Go to the [extension configuration](https://docs.typo3.org/permalink/web-vision/deepltranslate-core:extensionconfiguration@main)
    in **System > Settings > Extension Configuration**.

    > [!NOTE]
    > In TYPO3 v13 the path is **AdminTools > Settings > Extension Configuration**.
1.  Open the settings for **deepltranslate_core > Settings** and add your API key.

    ![The Extension configuration settings showing the input field for DeepL API key](../../Images/Reference/configuration-settings-deeplapikey.png)

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

> [!NOTE]
> Extension configuration provides additional API settings, currently unused
> and prepared for upcoming integration.

**Further Readings**

-   [Global extension configuration](https://docs.typo3.org/permalink/web-vision/deepltranslate-core:extensionconfiguration@main)

## Set up translation language {#sitesetup}

1.  Go to **Site Management > Sites** and edit your site configuration
1.  Switch to tab `Languages` and open your target

    ![Site settings for a TYPO3 language showing empty DeepL Target Language dropdown](../../Images/Administration/site-config-deepl-settings-empty.png)
1.  Go to **DeepL Settings** and set up your `Target Language (ISO Code)`

    ![Selected target now set to German](../../Images/Administration/site-config-selected-target.png)

> [!NOTE]
> Although the drop-down list can also be set in the default language, there is
> no point in defining a target language for the source language.

## Choice a Formality {#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.
>
> ![Selected target now set to German wird default formality](../../Images/Administration/site-config-selected-target-formally.png)

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

-   **deeplFormality**

    -   *type:* string

    Sets whether the translated text should lean towards formal or informal language.
    Possible options:

    -   **default**

        The default setting. If formal or informal depends on the language

    -   **less**

        Less formal language. Will fail, if no formality support for language

    -   **more**

        More formal language. Will fail, if no formality support for language

    -   **prefer_less**

        Use less formal language, if possible, otherwise fallback to default

    -   **prefer_more**

        Use more formal language, if possible, otherwise fallback to default

## Describe the site for DeepL {#translationcontext}

DeepL translates every field on its own. Short fields like headings or button
labels give it little to go by, so an ambiguous word may be translated in the
wrong meaning. A translation context describes the content in a few sentences,
for example its subject and audience. DeepL reads it, but does not translate
it, and its characters are not billed.

-   **deeplContext**

    -   *type:* string

    **Translation context** in the **DeepL** tab of the site
    configuration. Sent with the translations of all pages and records of the
    site, for example:

    **config/sites/\<identifier>/config.yaml**

    ```yaml
    deeplContext: 'The website of a tennis club in Berlin, for its members and guests. Members book tennis courts online.'
    ```

A page replaces the context of its site with the field
**Translation context** in the **DeepL Translate** tab of its
page properties, for the page and the records on it. Subpages do not inherit
it. Editors need the permission for this excluded field in their backend group.

Extensions change the context with the event
`\WebVision\Deepltranslate\Core\Event\DeepLContextEvent`, see
[Feature: Translation context of sites and pages](https://docs.typo3.org/permalink/web-vision/deepltranslate-core:feature-translation-context-of-sites-and-pages-1790976199@main).

## Configure tables {#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 [table configuration](https://docs.typo3.org/permalink/web-vision/deepltranslate-core:tableconfiguration@main) for details, and
[Content Blocks](https://docs.typo3.org/permalink/web-vision/deepltranslate-core:tableconfigurationcontentblocks@main) for fields defined
with Content Blocks.

## Detecting target language {#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
1.  Check hreflang against DeepL supported languages
    \* Needed for detecting EN-GB, EN-US, PT-PT or PT-BR
1.  Fallback to Language ISO code

For currently allowed languages see the [DeepL conform language key](https://developers.deepl.com/docs/api-reference/languages). 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.