Making the tables of an extension translatable
An extension describes its database tables in the Table Configuration Array (TCA). The TCA defines the fields in a record and how the backend should display them in a form. A translation is a record which points to the record in the default language in the same table. To make records in a table translatable, set the language properties in the [ctrl] section of the table's TCA:
<?php
return [
'ctrl' => [
'title' => 'my_extension.db:conference',
'label' => 'title',
'descriptionColumn' => 'internal_notes',
'default_sortby' => 'conference_date DESC',
'tstamp' => 'tstamp',
'crdate' => 'crdate',
'delete' => 'deleted',
'editlock' => 'editlock',
'enablecolumns' => [
'disabled' => 'hidden',
'starttime' => 'starttime',
'endtime' => 'endtime',
'fe_group' => 'fe_group',
],
'languageField' => 'sys_language_uid',
'transOrigPointerField' => 'l10n_parent',
'transOrigDiffSourceField' => 'l10n_diffsource',
'translationSource' => 'l10n_source',
'versioningWS' => true,
'origUid' => 't3_origuid',
'iconfile' => 'EXT:my_extension/Resources/Public/Icons/Conference.svg',
'security' => [
'ignorePageTypeRestriction' => true,
],
],
'columns' => [
'title' => [
'label' => 'my_extension.db:conference.title',
'config' => [
'type' => 'input',
'required' => true,
'max' => 255,
'eval' => 'trim',
],
],
'conference_date' => [
'label' => 'my_extension.db:conference.conference_date',
'config' => [
'type' => 'datetime',
'format' => 'date',
'required' => true,
],
],
'internal_notes' => [
'label' => 'my_extension.db:conference.internal_notes',
'config' => [
'type' => 'text',
'rows' => 3,
],
],
],
'types' => [
'0' => [
'showitem' => '
title, conference_date,
--div--;core.form.tabs:access,
hidden, --palette--;;access, fe_group, editlock,
--div--;core.form.tabs:language,
--palette--;;language,
--div--;core.form.tabs:notes,
internal_notes,
',
],
],
'palettes' => [
'access' => [
'label' => 'core.form.palettes:access',
'showitem' => 'starttime, endtime',
],
'language' => [
'showitem' => 'sys_language_uid, l10n_parent',
],
],
];
TYPO3 will than automatically add the TCA "columns" of these fields and the
database fields behind them. See
Auto-created columns from 'ctrl'.
TYPO3 does not automatically display the fields in the form. You need to add
them in the types section. The example above adds a language tab to the form with
two fields: the language and a reference to the original record that is in the
default language.
The form of a translation shows the default language values of the record below each field:
The Spanish translation of a conference, with the English title as a hint
Content
[languageField]
The first field is the languageField property and contains a reference to the language the record is in.
Note
This field was traditionally named sys_, but you can register
the field using any name.
The field has TCA type language, which contains the site languages and the language [All]. TYPO3 migrates a field of another type to this type, and can lose parts of its configuration on the way. See Migration to the language type.
[transOrigPointerField]
The second field is the
transOrigPointerField
property and contains a reference to the record in the default language. The
two fields belong together, so TYPO3 uses the name l10n_ for a table
that defines language but not trans.
Note
This field was traditionally named l10n_, but any name can be
used since it is registered with the trans property.
The l18n_ name used in table tt_ is a historical
mistake.
The field is only displayed in records that are not in the default language, as a record in the default language has nothing to point to.
It will only reference records in the default language if those records are on
the same page as the translation. This means that a
default language record and all its translations must be on the same page!
This principle is respected by the API function
Page
which fetches translations of records for the frontend display.
The form of a translation displays the values of the record that the field points to below its fields.
Warning
The configured
$GLOBALS cannot be
excluded as this leads to inconsistent data stored in the database. This
happens when a non-admin user creates a localization but does not have
permission to edit the trans. Remove
exclude => true
from TCA, if set.
[transOrigDiffSourceField]
There is one more field which can be used on a translatable table. It is defined in
the property
transOrigDiffSourceField
and is optional. It points to a blob database field which stores the
content of the default language record as it was when the translation was
originally made. This is then used to display any new changes that have occurred in the
default record since translation. For example, in the tt_
table, the header field may look like this:
Changes in the original content are highlighted below the input field
This allows a translator to easily spot what has changed.
[translationSource]
The "translationSource"
property defines the name of the field that is used by translations to point
back to the original record (that means, the record in the language of which
they are a translation). This property is often set to l10n_ in Core
tables.
This property is similar to
transOrigPointerField.
In connected mode, while
trans 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 there is a tt_ record in a default language (English) with
uid 13, and this record is translated to French with uid 17, and a Danish
translation is later created based on the French translation, then the Danish
translation will have uid 13 set as l10n_ and uid 17 as l10n_.
DataHandler commands for localization
The DataHandler writes any changes that the backend makes to records. The DataHandler "localize" command translates records. The backend runs this command when you translate an element in Content > Records or Content > Layout.
When this command is run an ordinary copy is made, but the languageField and transOrigPointerField fields are updated.
You can only localize a record which is not already localized and which has language set to "default" or "All" (a record with language "All" is classed as valid for any language, but can still be translated).
It is possible to manually create two or more translations of the same record but this is considered to be an error in the system. Although not fatal, it can produce unpredictable results.
Localization command options per field
Each field may contain special instructions which will affect the "localize" command. The most important is the "l10n_mode" field which, for example, can entirely exclude a field from the translation process.