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:

EXT:my_extension/Configuration/TCA/tx_myextension_conference.php
<?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',
    ],
  ],
];
Copied!

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 form of a Spanish conference, with the English title as a hint

The Spanish translation of a conference, with the English title as a hint

[languageField] 

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

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_parent for a table that defines languageField but not transOrigPointerField.

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 PageRepository::getLanguageOverlay() 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.

[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_content table, the header field may look like this:

The header of a translation, with the change of the English header

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_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 there is a tt_content 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_parent and uid 17 as l10n_source.

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.