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 the ICU MessageFormat style: 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]);

Copied!

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');

Copied!

param $reference

The label reference string (with or without the 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