Adding Languages

The Site Management > Sites 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 list 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.

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
languages:
  - languageId: 0
    title: English
    navigationTitle: ''
    base: /
    locale: en_GB.UTF-8
    flag: gb
Copied!

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
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 should have at last one language configured - with languageId: 0.

title
type

string

Example

English

The internal human-readable name for this language.

websiteTitle
type

string

Example

My custom very British title

Overrides the global website title for this language.

type

string

Example

British

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

base
type

string / URL

Example

/uk/

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

baseVariants
type

array

Allows different base URLs for the same language. They follow the same syntax as the base variants on the root level of the site config and they get active, if the condition matches.

Example:

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"'
Copied!
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
type

string

Example

en-GB

Changed in version 12.4

The information is now automatically derived from the locale setting.

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

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.
typo3Language
type

string

Example

en

Deprecated since version 12.3

It is not needed to set this property anymore, and is removed from the backend UI. The information is now automatically derived from the locale setting. Using this property will trigger a PHP deprecation notice.

Language identifier to use in TYPO3 XLIFF files.

flag
type

string

Example

gb

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

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
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.