Locale

New in version 12.2.

The \TYPO3\CMS\Core\Localization\Locale class unifies the handling of locales instead of dealing with "default" or other TYPO3-specific namings.

The Locale class is instantiated with a string following the IETF RFC 5646 language tag standard:

use TYPO3\CMS\Core\Localization\Locale;

$locale = new Locale('de-CH');

A locale supported by TYPO3 consists of the following parts (tags and subtags):

  • ISO 639-1 / ISO 639-2 compatible language key in lowercase (such as fr for French or de for German)

  • optionally the ISO 15924 compatible language script system (4 letter, such as Hans as in zh_Hans)

  • optionally the region / country code according to ISO 3166-1 standard in upper camelcase such as AT for Austria.

Examples for a locale string are:

  • en for English

  • pt for Portuguese

  • da-DK for Danish as used in Denmark

  • de-CH for German as used in Switzerland

  • zh-Hans-CN for Chinese with the simplified script as spoken in China (mainland)

The Locale object can be used to create a new LanguageService object via the LanguageServiceFactory for translating labels. Previously, TYPO3 used the default language key, instead of the locale en to identify the English language. Both are supported, but it is encouraged to use en-US or en-GB with the region subtag to identify the chosen language more precisely.

Example for using the Locale class for creating a LanguageService object for translations:

EXT:my_extension/Classes/LocaleExample.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Localization\LanguageServiceFactory;
use TYPO3\CMS\Core\Localization\Locale;

final class LocaleExample
{
    public function __construct(
        private readonly LanguageServiceFactory $languageServiceFactory
    ) {
    }

    public function doSomething()
    {
        $languageService = $this->languageServiceFactory->create(new Locale('de-CH'));
        $myTranslatedString = $languageService->sL(
            'LLL:EXT:my_extension/Resources/Private/Language/myfile.xlf:my-label'
        );
    }
}

API

class TYPO3\CMS\Core\Localization\Locale
A representation of

language key (based on ISO 639-1 / ISO 639-2)

  • the optional four-letter script code that can follow the language code according to the Unicode ISO 15924 Registry (e.g. HANS in zh_HANS)

  • region / country (based on ISO 3166-1)

separated with a "-".

This conforms to IETF - RFC 5646 (see https://datatracker.ietf.org/doc/rfc5646/) in a simplified form.

constant RIGHT_TO_LEFT_LANGUAGE_CODES
:php:`array (

0 => 'ar', 1 => 'arc', 2 => 'arz', 3 => 'ckb', 4 => 'dv', 5 => 'fa', 6 => 'ha', 7 => 'he', 8 => 'khw', 9 => 'ks', 10 => 'ps', 11 => 'sd', 12 => 'ur', 13 => 'uz-AF', 14 => 'yi',

)`, type array

getName()
Return type

string

getLanguageCode()
Return type

string

isRightToLeftLanguageDirection()
Return type

bool

getLanguageScriptCode()
Return type

string

getCountryCode()
Return type

string

getDependencies()
Return type

array

__toString()
Return type

string