All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh


From TYPO3Wiki
Jump to: navigation, search

<- Back to blueprints overview

Blueprint: FAL Localization

Proposal Make FAL records and it's meta data translatable
Owner/Starter Andreas Wolf
Participants/Members Steffen Ritter, Ernesto Baschny, Helmut Hummel
Status Draft, Discussion, Voting Phase, Accepted, Declined, Withdrawn
Current Progress Unknown, Started, Good Progress, Bad Progress, Stalled, Review Needed
Topic for Gerrit FALtranslation

Target Versions/Milestones

  • Basic version until 6.2 feature freeze (Phase 1)
  • Bugfixes and stabilizing API until 6.2 release
  • Enhanced version after 6.2 release (Phase 2)

Goals / Motivation

Meta data of files (title, description, etc) needs to be translatable for backend users. Frontend rendering should consider the relevant translation when displaying the content.

The DAM (digital asset management) extension already allows to do that. We need to have this feature in 6.2 to be able to support a migration from TYPO3 4.5 + DAM without running in the risk that several ways of "translating FAL records" appear in near future.


Translations in FAL has many ramifications and use-cases:

  1. A file could have meta data in different languages.
  2. Files could by themselves have a "language" (i.e. a PDF containing an German text).
  3. TYPO3's "default language" (sys_language_uid=0) concept clashes with FAL:
    1. A multiple branches TYPO3 installation could define a different default language per branch.
    2. A file record (sys_file) by itself is stored in page uid=0, so it's impossible to pin that file to a specific page branch (like in DAM): no way to automatically identify the "default language" of a file.

Our initial goal is to support at least the most common scenario 1 (for 6.2 LTS, using TYPO3's already known and stable localization features), while providing a concept to solve scenarios 2 and 3 in future (for the next releases - introducing a whole new concept to TYPO3: Locales).

Phase 1: Implementation Details

1) Split File and Meta Data

File information (not localizable) and metadata (localizable, like title, description, ...) are separated into two tables (sys_file and sys_file_metadata). Every file has one record in sys_file and 0..n records in sys_file_metadata.

  • File data (sys_file) itself is currently not planned to be extensible, but this might be required (e.g. Exif data).
  • File data is not versioned (at least for 6.2 LTS).
  • Metadata can be extended by extensions (adding new properties).
  • Metadata can be versioned and thus workspaced (for 6.2 LTS).

2) Introduce Translation for Meta Data

sys_file_metadata should then be translated using regular TYPO3 mechanisms in the backend.

3) GUI / Backend

  • Filelist view should provide edit icons to edit the "Metadata" record instead of the File record
  • Localization is done via a select box in EditDocumentController
    • standard mechanism as for all other records
    • provide a way to limit languages per Storage
  • ...

4) Frontend Rendering

The FE rendering should use the already existing content fallback mechanisms for fetching the relevant records.

Different default languages per tree: intermediate solution

The use-case of multiple trees with different default languages could be solved by administrator configuration and some conventions:

  • Define one Storage per default language (i.e. "files/en/" and "files/de/").
  • Limit translation per storage to the required translation languages.
  • Allow users to only use files from a specific "Language Storage" in certain page trees - thus making sure that the default language is always consistent.
  • Drawback: If the same file is to be used in different branches with different default languages those will have to be maintained separately.

Phase 2: Future Concept - Locales

The same problem with "multiple default languages" trees that we identified for files are also present for other types of records. I.e. no easy way of providing a central News folder with translated news if every page tree considers sys_language_uid=0 as a different language.

So the concept to go for after the basic FAL localization handling is done is to enhance the Core itself with proper support for Locales for records in general.

Fallback chain

  • Fallbacks for locale can be defined with the sys_language record
  • Fallback chain can be longer (not only xx -> default language as with sys_language_uids, but also e.g. en_GB -> en -> de_DE -> de)
  • usual fallback mechanisms defined with TCA should apply
  • need to be implemented for FormHandler; currently it only supports one-time fallback


  • Performance when retrieving records in a chain of localization

Locales for FAL records

  • This approach also might make it possible to change the file for a localization (e.g. manuals in different languages), but automatically have the correct file chosen for each language
  • reference from sys_file_metadata to sys_file is done with file_uid field
  • by default, file metadata should be for all languages (locale zz-MUL)


  • introducing a new localization method can create problems at various places, e.g. with versioning/workspaces. The concept should be discussed with experts in this area.
  • selecting the localized version of a record is quite cumbersome with possibly deeply nested fallback chains and different l10n_original records. This could lead to performance problems e.g. when records are translated not based on the fallback chain (because these records would not be selected when selecting the fallback chain)

Considering the risks we chose to postpone this topic for a future release of TYPO3 after 6.2 LTS to avoid putting an incomplete and potentially buggy implementation into such an important release.

Nevertheless the concept in this blueprint should serve as a basis for further thoughts and could be refined further.

API stability

Considering the future direction of localization with locales, the FAL external API should be kept stable even if in future we switch the localization method - the external API should thus be decoupled from the internal localization method. This allow extensions to continue working without modifications and provide a smooth upgrade path at least in this area.

Issues and reviews

Dependencies upon other Blueprints


External links for clarification of technologies