Translator API 

Instances of \TYPO3\CMS\Core\Localization\TranslatorInterface translate strings in plain PHP.

For examples see Localization in PHP. Create a TranslatorInterface with LanguageServiceFactory.

In the backend context a TranslatorInterface is stored in the global variable $GLOBALS['LANG'].

In the frontend a TranslatorInterface can be accessed via the contentObject:

<?php

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Localization\LanguageServiceFactory;

final class ExampleController
{
    private ServerRequestInterface $request;

    public function __construct(
        private readonly LanguageServiceFactory $languageServiceFactory,
    ) {}

    public function processAction(
        string $content,
        array $configurations,
        ServerRequestInterface $request,
    ): string {
        $this->request = $request;

        // ...
        $content .=  $this->getTranslatedLabel(
            'my_extension.messages:labels.exampleLabel',
        );
        // ...

        return $content;
    }

    private function getTranslatedLabel(string $key): string
    {
        $language = $this->request->getAttribute('language')
            ?? $this->request->getAttribute('site')->getDefaultLanguage();
        /** @var \TYPO3\CMS\Core\Localization\TranslatorInterface $translator */
        $translator = $this->languageServiceFactory
            ->createFromSiteLanguage($language);

        return $translator->label($key);
    }
}

In the CLI context the global $GLOBALS['LANG'] is not available and has to be instantiated manually.

interface TranslatorInterface

Fully qualified name

\TYPO3\CMS\Core\Localization\TranslatorInterface

Interface for translation services.

This interface provides a clean abstraction for translating labels in TYPO3. It uses ICU MessageFormat style where pluralization and other complex formatting logic is embedded in the message string itself, not in the API signature.

Example usage:

// Simple translation $translator->translate('button.save', 'backend.messages');

// Translation with arguments (sprintf-style placeholders) $translator->translate('record.count', 'backend.messages', [5]);

// ICU MessageFormat style for plurals (message: "{count, plural, one {# item} other {# items}}") $translator->translate('items.count', 'backend.messages+intl-icu', ['count' => 5]);

translate ( string $id, string $domain, array $arguments = [], ?string $default = NULL, ?TYPO3\CMS\Core\Localization\Locale|string|null $locale = NULL)

Translate a label by its identifier and domain.

param $id

The label identifier/key

param $domain

The translation domain (file reference like 'EXT:core/Resources/Private/Language/locallang.xlf'or semantic domain like 'core.messages'). For ICU MessageFormat, suffix with '+intl-icu'.

param $arguments

Optional arguments for placeholder replacement. For sprintf-style messages,pass indexed values. For ICU messages, pass named values (e.g., ['count' => 5])., default: []

param $default

Optional default value, default: NULL

param $locale

Optional locale override. If null, uses the service's configured locale., default: NULL

Return description

The translated string, or null if the label was not found

Returns

string|Stringable|null

label ( string $reference, array $arguments = [], ?string $default = NULL, ?TYPO3\CMS\Core\Localization\Locale|string|null $locale = NULL)

Translate a label by its full reference string.

Resolves TYPO3 label reference strings in the formats:

'core.messages:labels.depth_0' 'LLL:EXT:core/Resources/Private/Language/locallang_core.xlf:labels.depth_0' 'EXT:core/Resources/Private/Language/locallang_core.xlf:labels.depth_0'

The LLL: prefix is optional and stripped before resolution.

Example usage:

// Simple reference $translator->label('myext.messages:button.save');

// Simple reference (discouraged with file reference) $translator->label('LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:button.save');

// With arguments $translator->label('core.messages:record.count', [5]);

// With default value $translator->label('core.messages:missing.key', [], 'Fallback text');

param $reference

The label reference string (with or without LLL: prefix)

param $arguments

Optional arguments for placeholder replacement, default: []

param $default

Optional default value returned when the label is not found, default: NULL

param $locale

Optional locale override. If null, uses the service's configured locale., default: NULL

Return description

The translated string, the default value, or null if the label was not found

Returns

string|Stringable|null