About this document

Creating a website in multiple languages with TYPO3 can be done in a variety of ways - as usual. Unfortunately, all the options are hard to understand unless described in a context where used. In addition, even if you understand the context you might like to get some suggestions for what others have found to be best-practices.

This document tries to document everything you need to know about localizing websites with TYPO3. Ideally, it should mention every feature and what it is good for. However, be sure to use reference documents like the TypoScript Reference, TYPO3 Explained, etc. to look up the exact syntax for the features mentioned.

Since the main goal of this document is to include all knowledge areas of localization, it might suffer from a poor composition where advanced content is mixed here and there. A later revision could maybe make up for this by better prioritizing the content. For now that has not been a priority. On the other hand, you will come out as an expert in the other end.

Credits

This document was originally written by Kasper Skårhøj.

Database field lengths

The TYPO3 Core is compatible with UTF-8.

However, you might face the problem that the database field lengths of some extensions need to be extended. For example, each Chinese glyph takes three bytes. So if a field is a varchar(10) and an author enters 10 Chinese glyphs, only the first 3 glyphs will be stored (as they require 9 bytes). UTF-8 is tricky in this respect, as all ASCII characters only need 1 byte, while European special characters usually need 2 and Asian character sets 3 bytes - but some special characters can even need 5-6 bytes!

Site Management

The Introduction Package's default languages are English, Danish and German languages. Adding a new language is done in the Site Management > Sites module of the backend.

Once you have defined at least one additional language, you will be able to translate pages and content. For example, the Web > List module will show links for translation if you have translated the page.

Translated elements appears nested "under" their default language parent element in the Web > List view.

Introduction

You can get a complete overview of the page tree and page translations by using the Web > Info module and choosing the Localization Overview function.

All the green entries indicate which languages the respective page is available in. The gray areas mean that no translation is available, but access to the page specifying this language is tolerated. It is also fast to create new translations from this module: use the checkboxes and hit the Create new translation headers button.

Hiding pages if no translation exist

If there is no translation of a page, it will still appear by default in the website menu when this language is used. Here the home page of the Introduction Package is in German (as can be seen from the translate page title in <title> tag), and all other (untranslated) pages still appear in the menu, albeit in the default language (English).

This behaviour can be changed. Let us edit the "Customizing" page. In the Language tab, check the Hide page if no translation for current language exists:

This is reflected in the Localization Overview:

From this it is clear that when viewing the website in German the "Customizing" page is not accessible. The menu reflects this in the frontend.

Trying to access the "Customizing" page directly with its ID will produce an error.

Hiding default translation of pages

If you want pages only in the alternative languages you must still create a default language page in the page tree which simply acts as a placeholder. Setting this status is done by selecting the checkbox Hide default translation of page:

This is reflected in the Localization Overview:

On the web site, the menu now looks like this in German:

and in English:

Trying to access the "Nur für Deutschland" page in the default language will yield an error.

Hiding pages in the default language is probably a rare thing to do, but it is possible to imagine cases where the topic of a page or section is only relevant in one of the alternative languages. Especially, if a language of the site is not only a translation but may serve subsidiaries of a company in a local context.

Inverse control of hidden translations

It is also possible to hide all untranslated pages by default with a global setting:

$GLOBALS['TYPO3_CONF_VARS']['FE']['hidePagesIfNotTranslatedByDefault'] = 1;

The Localization Overview reflects this immediately:

Note how the behaviour of specific localization setting for the "Customizing" pages has been inverted. We had earlier defined the page to be hidden if no translation existed. Now it is forced to display even if no translation exists (this is reflected by its background being gray instead of red).

When editing the page properties, the label of the corresponding checkbox has changed:

Final notes

Summary of colors in the Localization Overview:

Green background

Page is translated and viewable in this language. For translations it means that an active Alternative Page Language overlay record is present.

Red background

Page cannot be viewed in this language and you will see an error message if you try. Menus should automatically filter out links to pages with this translation.

Gray background (not available for default language)

Page will fall back to the specified fallback mode for content. It depends on the language fallback configuration set in your site configuration.

Introduction

There are two strategies for handling the translation of content on pages:

Connected mode

Translating content will create a direct connection between the original language and the language you translate to. This means that moving an element or setting meta information like start time or end time will be taken from the original content and you will not be able to set these values on a translated content element. Translated records will hold the connection to their original language record in the l10n_parent field. This mode is best for a strict translation workflow.

Free mode

Copying content will take the content elements from the source language and create copies in a different language. This means that you will be able to move content elements around freely, but you will not have the benefit of being able to compare changes made in the source language later on. Use this mode, when the translated pages content can largely differ from the original language and you want to have that freedom in designing your translated website.

When you start translating a page, the Web > Page module will ask you about this choice when clicking on the Translate button:

The Translate button corresponds to the connected mode, the Copy button to the free mode. Furthers details on how to proceed with translations are found in the Editor's Tutorial.

Connected content

If you opted for the connected content strategy, this is the default way that translated pages will be handled in the frontend and requires no further configuration in the site configuration. In the site configuration, the fallbackType "strict" would look like this:

languages:
  -
    # ... other language settings ...
    fallbackType: strict

In this connected mode, TYPO3 will first internally fetch the records of the default language, then overlay them with the target language. If a record is not translated into the target language, then it is discarded and not shown at all.

The German version will be reduced to the actually translated elements:

Another way to view connected content in the frontend is by creating a fallback chain. For this we have to adjust the site configuration and provide a comma-separated list of fallback languages:

languages:
  -
    # ... other language settings ...
    fallbackType: fallback
    # 1 = Danish, 0 = English
    fallbacks: '1,0'

In this mode, TYPO3 will also first internally fetch the records of the default language and then overlay them with the target language. If no translation exists for the target language, it will now go from left to right through the fallback chain and first try to find a translation for the language ID 1 (Danish) and, if that is a miss as well, fall back to language ID 0 (English).

Free content

With the free mode content strategy, the site configuration will have to be adjusted accordingly:

languages:
  -
    # ... other language settings ...
    fallbackType: free

This means, TYPO3 will directly fetch the translated records and not care about the records in the default language at all.

The "All" language

When using overlays, it becomes possible to use a particular language called "All", which will be automatically visible across all translations. The uid of that particular language is "-1".

It is also marked with the special language icon in the Web > Page module:

Note that no Translate button appears, the new content element is valid for all languages.

Localizing inline elements (IRRE)

When localizing a record with inline elements (IRRE), the inline elements will be grayed out and not automatically localized. TYPO3 will display two buttons to help you localize and keep the elements in sync.

Localize all records (1) creates localized versions of all inline elements from the default language in your current language so that you can translate them. Each element that has not yet been localized will also have a Localize button (3) that will allow you to localize individual elements.

Synchronize with original language (2) can be clicked when you have translated the elements and the content in the default language changed.

Using XLF labels in TypoScript structures

XLIFF (XLF) files are XML files containing labels that the system can retrieve in a localized version if the appropriate translations are installed. It is possible to retrieve values from XLF files using TypoScript:

page.20 = TEXT
page.20.data = LLL:EXT:indexed_search/Resources/Private/Language/locallang.xlf:form.submit

This looks for the label form.submit in the file Resources/Private/Language/locallang.xlf from the extension "indexed_search".

If the frontend is now accessed in the language "de", the German language is configured in the site configuration and the German translations are installed in getLabelsPath()/de/, the output should be "Suche" (instead "Search" which is what you will get if the label is retrieved for the default language).

Using XLF labels in frontend plugins

Making your code ready for internationalization is covered in Localization and basics about XLIFF files are found in XLIFF Format ("TYPO3 Explained"). Properly made plugins should use XLIFF files for every label that they used, so that they can be translated and thus generate a proper output when a specific language is requested.

For instance, if the page is accessed in the language "de" and the German translations are installed, you will see this page for "indexed search":

Overriding an existing translation is possible using custom XLIFF files. This process is described in Custom translations.

It is also possible to override a label using TypoScript. See the TypoScript Reference for more information.

You can also create XLIFF files for a language into which TYPO3 is not translated yet. This process is described in Custom languages.

LanguageMenuProcessor example

The Introduction Package comes with a text-based rendering of the language menu, located in the footer:

This is the corresponding TypoScript code, that sets up a LanguageMenuProcessor on the page level:

page = PAGE
page {
  10.dataProcessing {
    40 = TYPO3\CMS\Frontend\DataProcessing\LanguageMenuProcessor
    40 {
      languages = <insert language-id> or "auto"
      as = languagenavigation
    }
  }
}

The value for languages is a list of comma-separated language IDs (for example: 0,1,2) or auto to load from site configuration.

The menu is then passed as a hierarchical array to Fluid in the variable {languagenavigation}. The Fluid template iterates through the array and creates the language links:

<f:if condition="{languagenavigation}">
    <ul id="language_menu" class="language-menu">
        <f:for each="{languagenavigation}" as="item">
            <li class="{f:if(condition: item.active, then: 'active')} {f:if(condition: item.available, else: 'text-muted')}">
                <f:if condition="{item.available}">
                    <f:then>
                        <a href="{item.link}" hreflang="{item.hreflang}" title="{item.title}">
                            <span>{item.navigationTitle}</span>
                        </a>
                    </f:then>
                    <f:else>
                        <span>{item.navigationTitle}</span>
                    </f:else>
                </f:if>
            </li>
        </f:for>
    </ul>
</f:if>

[languageField]

The first field is defined by the "languageField" property and contains a reference to the language the record is in.

Here is how such a field is configured (example from the tt_content table):

'sys_language_uid' => [
    'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.language',
    'config' => [
        'type' => 'language'
    ]
]

The entry for the [All] language gets automatically added with the TCA type language.

[transOrigPointerField]

The first field is defined by the "transOrigPointerField" property and contains a reference to the record in the default language.

Here is how such a field is configured (example from the tt_content table):

'l10n_parent' => [
    'displayCond' => 'FIELD:sys_language_uid:>:0',
    'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.l18n_parent',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            ['', 0]
        ],
        'foreign_table' => 'tt_content',
        'foreign_table_where' => 'AND {#tt_content}.{#pid}=###CURRENT_PID### AND {#tt_content}.{#sys_language_uid} IN (-1,0)',
        'default' => 0,
    ],
],

Obviously, the table name has to be adapted in properties foreign_table and foreign_table_where for each table.

Notice the display condition set on the field, which will check the value of the sys_language_uid and display the l18n_parent field only when it is greater than zero (that means, it is a translation).

Another interesting point is that it will only look for a default language record in the current pid. This means that a default language record and all its translations must be on the same page! This principle is also respected by the API function \TYPO3\CMS\Core\Domain\Repository\PageRepository::getLanguageOverlay() which fetches translations of records for the frontend display.

When the transOrigPointerField and languageField are defined for a table you will see references to the content of the default language record when editing the translation:

[transOrigDiffSourceField]

There is one more field which can be used on a translatable table, defined by the property "languageField". It is optional. It points to a blob database field which will store the content of the default language record as it was when the translation was made. Then this is used to display any changes that have occurred in the default record since translation happened. For example, in the tt_content table, it may look like this for the header field:

This allows a translator to spot easily what has changed in order to adjust the translation accordingly.

[translationSource]

The "translationSource" property defines a name of the field used by translations to point back to the original record (that means, the record in any language of which they are a translation). This property is often set to l10n_source in Core tables.

This property is similar to transOrigPointerField. In connected mode, while transOrigPointerField always contains the uid of the default language record, this field contains the uid of the record the translation was created from.

For example, if a tt_content record in default language (English) with uid 13 exists, this record is translated to French with uid 17, and the Danish translation is later created based on the French translation, then the Danish translation has uid 13 set as l10n_parent and 17 as l10n_source.

DataHandler commands for localization

Localizing a record can be done by the "localize" command of the DataHandler. This is the command that is sent when you press the translate buttons in Web > List or Web > Page for an element.

When this command is issued an ordinary copy is made but the fields languageField and transOrigPointerField are updated accordingly.

You can only localize a record which is not already localized and which is in "default" or "All" language (a record in "All" language is supposed to be somehow valid for any language, but can still be translated if needed).

It is possible to manually create two or more translations of the same record but this is considered an error in the system, although not fatal, yet producing unpredictable results.