---
title: "Adding languages"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:sitehandling-addinglanguages@main"
source: "ApiOverview/SiteHandling/AddLanguages.rst"
modified: "2026-09-15T19:16:38+00:00"
---

# Adding languages

The **Sites > Setup** module lets you specify which languages
are active for your site, which languages are available, and how they
should behave. New languages for a site can also be configured in this module.

When the backend shows the list of available languages, the list of languages is
limited to the languages defined by the sites module. For instance, the
languages are used in the page module language selector, when editing records
or in the **Content > Records** module.

The language management provides the ability to hide a language on the frontend
while allowing it on the backend. This enables editors to start translating
pages without them being directly live.

> [!NOTE]
> In case no site configuration has been created for a tree, all configured
> languages are displayed. In this case the [page TSconfig options](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/PageTsconfig/Mod.html#pagemod) `mod.SHARED.defaultLanguageFlag`,
> `mod.SHARED.defaultLanguageLabel` and
> `mod.SHARED.disableLanguages` settings are also considered -
> those are obsolete, if a site configuration exists.

Language fallbacks can be configured for any language except the default one. A
language fallback means that if content is not available in the current language,
the content is displayed in the fallback language. This may include multiple
fallback levels - for example, "Modern Chinese" might fall back to "Chinese
(Traditional)", which in turn may fallback to "English". All languages can be
configured separately, so you can specify different fallback chains and
behaviors for each language.

Example of a language configuration (excerpt):

**config/sites/\<some_site>/config.yaml | typo3conf/sites/\<some_site>/config.yaml**

```yaml
languages:
  - languageId: 0
    title: English
    navigationTitle: ''
    base: /
    locale: en_GB.UTF-8
    flag: gb

```

## Configuration properties

-   **enabled**

    -   *Type:* bool
    -   *Example:* `true`

    Defines, if the language is visible on the frontend. Editors in the TYPO3
    backend will still be able to translate content for the language.

### languageId

-   **languageId**

    -   *Type:* integer
    -   *Example:* `1`

    For the default/main language of the given site, use value `0`. For
    additional languages use a number greater than `0`. Every site must
    have at last one language configured with `languageId: 0`.

    > [!WARNING]
    > **Attention**
    >
    > Once pages, content or records are created in a specific language, the
    > `languageId` must not be changed anymore.

### title

-   **title**

    -   *Type:* string
    -   *Example:* `English`

    The internal human-readable name for this language.

### websiteTitle

-   **websiteTitle**

    -   *Type:* string
    -   *Example:* `My custom very British title`

    Overrides the global website title for this language.

### navigationTitle

-   **navigationTitle**

    -   *Type:* string
    -   *Example:* `British`

    Optional navigation title which is used in
    `HMENU.special = language`.

### base

-   **base**

    -   *Type:* string / URL
    -   *Example:* `/uk/`

    The language base accepts either a URL or a path segment like `/en/`.

### baseVariants

-   **baseVariants**

    -   *Type:* array

    Allows different base URLs for the same language. They follow the same
    syntax as the [base variants](https://docs.typo3.org/permalink/t3coreapi:sitehandling-basevariants@main) on the root
    level of the site config and they get active, if the condition matches.

    Example:

    **config/sites/my-site/config.yaml (excerpt)**

    ```yaml
    baseVariants:
      -
        base: 'https://example.localhost/'
        condition: 'applicationContext == "Development"'
      -
        base: 'https://staging.example.com/'
        condition: 'applicationContext == "Production/Sydney"'
      -
        base: 'https://testing.example.com/'
        condition: 'applicationContext == "Testing/Paris"'

    # ...

    ```

-   **locale**

    -   *Type:* string / locale
    -   *Example:* `en_GB` or `de_DE.utf8,de_DE`

    The locale to use for this language. For example, it is used during frontend
    rendering. That locale needs to be installed on the server. In a Linux
    environment, you can see installed locales with `locale -a`. Multiple
    fallback locales can be set as a comma-separated list. TYPO3 will then
    iterate through the locales from left to right until it finds a locale that
    is installed on the server.

#### hreflang

-   **hreflang**

    -   *Type:* string
    -   *Example:* `en-GB`

    Use this property to override the automatic hreflang tag value for this
    language.

    The information is automatically derived from the
    [locale](https://docs.typo3.org/permalink/t3coreapi:sitehandling-addinglanguages-locale@main) setting.

    **Example setups:**

    -   You have "German (Germany)" (which is using `de-DE` as locale) and
        "German (Austria)" (which is using `de-AT` as locale). Here you
        want to set `de` as generic fallback in the `de-DE` locale
        when using hreflang tags.
    -   You want to explicitly set `x-default` for a specific language,
        which is clearly not a valid language key.

#### flag

-   **flag**

    -   *Type:* string
    -   *Example:* `gb`

    The flag identifier. For example, the flag is displayed in the backend page
    module.

#### fallbackType

-   **fallbackType**

    -   *Type:* string
    -   *Example:* `strict`

    The language fallback mode, one of:

    -   **`fallback`**

        Fall back to another language, if the record does not exist in the
        requested language. Do overlays and keep the ones that are not
        translated.

        It behaves like the old `config.sys_language_overlay = 1`.
        Keep the ones that are only available in default language.

    -   **`strict`**

        Same as `fallback` but removes the records that are not
        translated.

        If there is no overlay, do not render the default language records,
        it behaves like the old `hideNonTranslated`, and include
        records without default translation.

    -   **`free`**

        Fall back to another language, if the record does not exist in the
        requested language. But always fetch only records of this specific
        (available) language.

        It behaves like old `config.sys_language_overlay = 0`.

#### fallbacks

-   **fallbacks**

    -   *Type:* comma-separated list of language IDs
    -   *Example:* `1,0`

    The list of fallback languages. If none has a matching translation, a
    "pageNotFound" is thrown.