---
title: "Locale"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:locale-api@main"
source: "ApiOverview/Localization/LocalizationApi/Locale.rst"
modified: "2026-09-16T13:05:25+00:00"
---

# Locale

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](https://www.rfc-editor.org/rfc/rfc5646.html) language tag standard:

```php
use TYPO3\CMS\Core\Localization\Locale;

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

A locale supported by TYPO3 consists of the following parts
([tags and subtags](https://www.rfc-editor.org/rfc/rfc5646.html#section-2)):

-   [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) / [ISO 639-2](https://en.wikipedia.org/wiki/ISO_639-2) compatible language key in lowercase
    (such as `fr` for French or `de` for German)
-   optionally the [ISO 15924](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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
`TranslatorInterface` object via the
[LanguageServiceFactory](https://docs.typo3.org/permalink/t3coreapi:languageservicefactory-api@main) 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 of using the `Locale` class for creating a
`TranslatorInterface` object for
translations:

**EXT:my_extension/Classes/LocaleExample.php**

```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(): string
  {
    $translation = $this->languageServiceFactory->create(new Locale('de-CH'));
    return $translation->translate('my-label', 'my_extension.myfile');
  }
}

```

-   **class Locale**

    -   *Fully qualified name:* `\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/](https://datatracker.ietf.org/doc/rfc5646/)) in a simplified form.

    -   **getName()**

        *Returns:* `string`

    -   **getLanguageCode()**

        *Returns:* `string`

    -   **isRightToLeftLanguageDirection()**

        *Returns:* `bool`

    -   **getLanguageScriptCode()**

        *Returns:* `?string`

    -   **getCountryCode()**

        *Returns:* `?string`

    -   **getDependencies()**

        *Returns:* `array`

    -   **\_\_toString()**

        *Returns:* `string`