Localization in PHP

Sometimes you have to localize a string in PHP code, for example inside of a controller or a user function.

Which method of localization to use depends on the current context:

Localization in plain PHP

The \TYPO3\CMS\Core\Localization\LanguageService is available if a backend user has been initialized, in particular in the following contexts:

  • frontend: only if there is a logged-in backend user
  • backend: always, except in Admin Tools modules (e.g. within Upgrade Wizard in the backend)
  • install tool / install tool modules in backend (e.g. Upgrade Wizard): no
  • in cli: only if a backend user was initialized, e.g. by TYPO3\CMS\Core\Core\Bootstrap::initializeBackendUser()

The LanguageServiceFactory can be used to instantiate. Please see the examples below.

The methods provided by the instantiated LanguageService class then be used to translate texts using the language keys of XLIFF language files.

Localization in frontend context

In plain PHP use the class LanguageServiceFactory to create a LanguageService from the current site language:

EXT:my_extension/Classes/UserFunction/MyUserFunction.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend;

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

final class MyUserFunction
{
    private LanguageService $languageService;

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

    private function getLanguageService(
        ServerRequestInterface $request,
    ): LanguageService {
        return $this->languageServiceFactory->createFromSiteLanguage(
            $request->getAttribute('language')
            ?? $request->getAttribute('site')->getDefaultLanguage(),
        );
    }

    public function main(
        string $content,
        array $conf,
        ServerRequestInterface $request,
    ): string {
        $this->languageService = $this->getLanguageService($request);
        return $this->languageService->sL(
            'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:something',
        );
    }
}
Copied!

Dependency injection should be available in most contexts where you need translations. Also the current request is available in entry point such as custom non-Extbase controllers, user functions, data processors etc.

Localization in backend context

In the backend context you can use the global variable $GLOBALS['LANG'] which contains the LanguageService.

EXT:my_extension/Classes/Backend/MyBackendClass.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend;

use TYPO3\CMS\Core\Localization\LanguageService;

final class MyBackendClass
{
    private function translateSomething(string $input): string
    {
        return $this->getLanguageService()->sL($input);
    }

    private function getLanguageService(): LanguageService
    {
        return $GLOBALS['LANG'];
    }

    // ...
}
Copied!

Localization without context

If you should happen to be in a context where none of these are available, for example a static function, you can still do translations:

EXT:my_extension/Classes/Utility/MyUtility.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Utility;

use TYPO3\CMS\Core\Localization\LanguageServiceFactory;
use TYPO3\CMS\Core\Utility\GeneralUtility;

final class MyUtility
{
    private static function translateSomething(string $lll): string
    {
        $languageServiceFactory = GeneralUtility::makeInstance(
            LanguageServiceFactory::class,
        );
        // As we are in a static context we cannot get the current request in
        // another way this usually points to general flaws in your software-design
        $request = $GLOBALS['TYPO3_REQUEST'];
        $languageService = $languageServiceFactory->createFromSiteLanguage(
            $request->getAttribute('language')
            ?? $request->getAttribute('site')->getDefaultLanguage(),
        );
        return $languageService->sL($lll);
    }
}
Copied!

Localization in Extbase

In Extbase context you can use the method \TYPO3\CMS\Extbase\Utility\LocalizationUtility::translate($key, $extensionName).

This method requires the localization key as the first and the extension's name as optional second parameter. For all available parameters see below. Then the corresponding text in the current language will be loaded from this extension's locallang.xlf file.

The method translate() takes translation overrides from TypoScript into account. See Changing localized terms using TypoScript.

Example

In this example the content of the flash message to be displayed in the backend gets translated:

Class T3docs\Examples\Controller\ModuleController
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
use TYPO3\CMS\Extbase\Utility\LocalizationUtility;

class ModuleController extends ActionController
{
    /**
     * Adds a count of entries to the flash message
     */
    public function countAction(string $tablename = 'pages'): ResponseInterface
    {
        $count = $this->tableInformationService->countRecords($tablename);

        $message = LocalizationUtility::translate(
            'record_count_message',
            'examples',
            [$count, $tablename],
        );

        $this->addFlashMessage(
            $message ?? '',
            'Information',
            ContextualFeedbackSeverity::INFO,
        );
        return $this->redirect('flash');
    }
}
Copied!

The string in the translation file is defined like this:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<!-- EXT:examples/Resources/Private/Language/locallang.xlf -->
<xliff version="1.0">
    <file source-language="en" datatype="plaintext" original="messages" date="2013-03-09T18:44:59Z" product-name="examples">
        <header />
        <body>
            <trans-unit id="new_relation" xml:space="preserve">
                <source>Content element "%1$s" (uid: %2$d) has the following relations:</source>
            </trans-unit>
        </body>
    </file>
</xliff>
Copied!

The arguments will be replaced in the localized strings by the PHP function sprintf.

This behaviour is the same like in a Fluid translate ViewHelper with arguments.

Examples

Provide localized strings via JSON by a middleware

In the following example we use the language service API to provide a list of localized season names. This list could then be loaded in the frontend via Ajax.

You can finde the complete example on GitHub, EXT:examples, HaikuSeasonList.

As we do not need a full frontend context with TypoScript the JSON is returned by a PSR-15 middleware.

Beside other factories needed by our response, we inject the LanguageServiceFactory with constructor dependency injection.

Class T3docs\Examples\Middleware\HaikuSeasonList
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use TYPO3\CMS\Core\Localization\LanguageServiceFactory;

/**
 * This middleware can be used to retrieve a list of seasons with their according translation.
 * To get the correct translation the URL must be within a base path defined in site
 * handling. Some examples:
 * "/en/haiku-season-list.json" for English translation (if /en is the configured base path)
 * "/de/haiku-season-list.json" for German translation (if /de is the configured base path)
 * If the base path is not available in the according site the default language will be used.
 */
final readonly class HaikuSeasonList implements MiddlewareInterface
{
    public function __construct(
        private LanguageServiceFactory $languageServiceFactory,
        private ResponseFactoryInterface $responseFactory,
        private StreamFactoryInterface $streamFactory,
    ) {}
}
Copied!

The main method process() is called with a Psr\Http\Message\ServerRequestInterface as argument that can be used to detect the current language and is therefore passed on to the private method getSeasons() doing the actual translation:

Class T3docs\Examples\Middleware\HaikuSeasonList
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

final readonly class HaikuSeasonList implements MiddlewareInterface
{
    private const URL_SEGMENT = '/haiku-season-list.json';

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        if (!str_contains($request->getUri()->getPath(), self::URL_SEGMENT)) {
            return $handler->handle($request);
        }

        $seasons = json_encode($this->getSeasons($request), JSON_THROW_ON_ERROR);

        return $this->responseFactory->createResponse()
            ->withHeader('Content-Type', 'application/json')
            ->withBody($this->streamFactory->createStream($seasons));
    }
}
Copied!

Now we can let the \TYPO3\CMS\Core\Localization\LanguageServiceFactory to create a \TYPO3\CMS\Core\Localization\LanguageService from the request's language, falling back to the default language of the site.

The LanguageService can then be queried for the localized strings:

Class T3docs\Examples\Middleware\HaikuSeasonList
use Psr\Http\Message\ServerRequestInterface;

final readonly class HaikuSeasonList implements MiddlewareInterface
{
    private const SEASONS = ['spring', 'summer', 'autumn', 'winter', 'theFifthSeason'];
    private const TRANSLATION_PATH = 'LLL:EXT:examples/Resources/Private/Language/PluginHaiku/locallang.xlf:season.';

    /**
     * @return array<string, string>
     */
    private function getSeasons(ServerRequestInterface $request): array
    {
        $languageService = $this->languageServiceFactory->createFromSiteLanguage(
            $request->getAttribute('language') ?? $request->getAttribute('site')->getDefaultLanguage(),
        );

        $translatedSeasons = [];
        foreach (self::SEASONS as $season) {
            $translatedSeasons[$season] = $languageService->sL(self::TRANSLATION_PATH . $season);
        }

        return $translatedSeasons;
    }
}
Copied!