frontend localization guide - svti of ‘‘forcecharset’’ the reason is that without a value...

Frontend Localization GuideRelease 1.1.0

TYPO3 Documentation Team

2016-01-12 10:45

CONTENTS

1 Introduction 31.1 About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Basic setup of a localized website 52.1 Character sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Setting up languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Defining the “default” language flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 Translations of pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.5 Localization Overview of the page tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.6 Web>List localization view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.7 TypoScript configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.8 Localization mode: “config.sys_language_mode” . . . . . . . . . . . . . . . . . . . . . . . . . . 122.9 llXML (locallang-XML) in plugins and TypoScript . . . . . . . . . . . . . . . . . . . . . . . . . 182.10 Language Selector Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3 Localized content 233.1 Content binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.2 FlexForms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.3 FlexForm - Containter Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.4 Inheritance settings (specific for TemplaVoilà!) . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.5 Localized TemplaVoilà Template Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.6 TemplaVoilà Page Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.7 TemplaVoilà: Best-practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543.8 TemplaVoilà: Translator workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4 Core support for localization 594.1 TCA, TCEmain, TCEforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594.2 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

5 Extensions 635.1 realurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.2 l10ncm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.3 rlmp_language_detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

6 Todo list for localization features 65

i

CONTENTS

Previous Key doc_guide_l10n, doc_l10nguide

Version 1.1.0

Language en

Description This guide contains all the information you need, if you localize websites with TYPO3!

Keywords forAdmins, forDevelopers, forIntermediates

Copyright 2000-2013

Author Documentation Team

Email [email protected]

License Open Publication License available from www.opencontent.org/openpub/

Rendered 2016-01-12 10:45

The content of this document is related to TYPO3,

a GNU/GPL CMS/Framework available from www.typo3.org

Official Documentation

This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3Documentation Team following a peer- review process. The reader should expect the information in this documentto be accurate - please report discrepancies to the Documentation Team ([email protected]). Officialdocuments are kept up-to-date to the best of the Documentation Team’s abilities.

Guide

This document is a Guide. Guides are designed to familiarize a reader with a specific topic in order to provide aworking knowledge of that particular process. Readers should peruse the guide from cover to cover in order to gaina practical overview of the process. Once completed, the Guide becomes a practical reference tool that a reader willrefer to as needed. Guides offer advice on how best to achieve a given task.

Table of Contents

CONTENTS 1

mailto:[email protected]

http://www.opencontent.org/openpub/

https://typo3.org/


Frontend Localization Guide, Release 1.1.0

2 inspiring people to share.

CHAPTER

ONE

INTRODUCTION

1.1 About this document

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

This document tries to document everything there is to know about localization of websites with TYPO3. It shouldideally mention every feature and what it is good for. You must however make sure to use reference documents likeTSref, TYPO3 Core API etc. to look up the exact syntaxes for the features mentioned.

Both the classic column-based web designs and the modern TemplaVoilà approaches are covered by the document.

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

1.1.1 Free and Bound paradigms of localization with TemplaVoilà

During the work with this document I realized that it should have been around many years ago; it turned out thatmany people are already localizing websites but in a less efficient way than it could have been done. It lead to a lotof debate and eventually we realized that there exists different paradigms of how localization should be done. Sincemany existing websites are using a paradigm that is not recommended we decided to integrate configurable supportfor this in order to stay backwards compatible.

1.1.2 Localization and Translation

The two terms are often used to express the same. Also in this document. But more precisely this is how Iunderstand the difference:

• “Translation” means that a specific composition of words are translated to another language. In other words:If there is a header and an image in the default language, so there will be in the translation. No more, no less.

• “Localization” means more broadly that a page is represented in another language. This of course meansinformation in that language (“translation”) but could also include alternative templates, additional composi-tion of content directed to another audience etc. In other words: There might be another number of headersand images than in the default language.

TYPO3 handles both types of approaches, but this flexibility has the price that you need to read this document tofind out which approach to choose for your project!

3


1.2 Credits

This document was originally written by Kasper Skårhøj. It is currently not maintained.

1.2.1 Dedication

I want to dedicate this document to every native English speaker who has over the years learned to live withmy gazillions of documents full of weird syntactical compositions and understood that it was a privilege that anon-native like me after all chose to communicate in a foreign language to the best of my abilities.

- kasper

1.3 Feedback

For general questions about the documentation get in touch by writing to [email protected] .

If you find a bug in this manual, please be so kind as to check the online version onhttps://docs.typo3.org/typo3cms/FrontendLocalizationGuide/. From there you can hit the “Edit me on GitHub”button in the top right corner and submit a pull request via GitHub. Alternatively you can just file an issue using thebug tracker: https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-FrontendLocalization/issues.

Maintaining high quality documentation requires time and effort and the TYPO3 Documentation Team al-ways appreciates support. If you want to support us, please join the documentation mailing list/forum(http://forum.typo3.org/index.php/f/44/).



https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/

https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-FrontendLocalization/issues

http://forum.typo3.org/index.php/f/44/

CHAPTER

TWO

BASIC SETUP OF A LOCALIZED WEBSITE

This chapter will document all the basic requirements to set up a localized website in TYPO3. It will tellyou how to deal with character sets, how to define which pages are translated, backend tools for localization,configuring TypoScript to get the localization mode you wish. In addition you will learn about advanced featureslike locallang-XML files and translation of frontend plugins.

2.1 Character sets

Recommended for all new TYPO3 websites is to set the global character set to UTF-8. This is done by putting aline like this into the localconf.php file of the site:

$TYPO3_CONF_VARS['BE']['forceCharset'] = 'utf-8';

2.1.1 Explanation of ‘‘forceCharset’’

The reason is that without a value for “forceCharset” the backend will use a charset depending on the backendlanguage of the user. So lets say User A has a backend in Russian and User B a backend in Danish, then User Awill enter data in the charset “windows-1251” and User B in “iso-8859-1”. Since data stored in TYPO3 is nottagged with a charset this will lead to an inconsistent database.

If $TYPO3_CONF_VARS[’BE’][’forceCharset’]is set, the same charset is used for all users in the backendregardless of their backend language and you will get consistent data in your database. But since “iso-8859-1” and“windows-1251” are “incompatible” charsets (using the same byte values for different glyphs) you will have tochoose “utf-8” as charset since that can contain both danish and russian chars - and all other charsets of the world.

Conclusion: Using utf-8 means you have a consistent data storage and can store any glyph from any languagewithout thinking more about charsets.

Note: $TYPO3_CONF_VARS[’BE’][’forceCharset’]is not set by default for backwards compatibility reasons butis recommended for all new TYPO3 projects.

2.1.2 Charset in frontend (advanced)

The “forceCharset” value will also be used in the frontend automatically. But it is possible to change charsetsettings in TypoScript. There are two settings, “config.renderCharset” (don’t change unless you know what you aredoing) and “config.metaCharset”.

config.metaCharset defines the character set of the HTML output. If this is set to another value than renderCharset /forceCharset, all content is converted before output although internally processed in “renderCharset”. This is usefulfor special cases like japanese websites where they like “shift-jis” used for content delivery.

If config.renderCharset != config.metaCharset there are a few things to be aware of:

• Content from “PHP_SCRIPT_EXT” is not converted! (everything else is, including USER_INT)

5


• GET / POST data is automatically converted from metaCharset to renderCharset

2.1.3 Database field lengths

If you choose to use utf-8 as charset you might face the problem that the database field lengths must be extended.For example, each chinese glyph takes three bytes. So if a field is a varchar(10) and an author enters 10 chineseglyphs only the first 3 glyphs will be stored (since they take up 9 bytes). utf-8 is tricky in this respect because allascii chars take only 1 byte while european special chars typically take up 2 and asian charsets take up 3 - but somespecial glyphs could take even 5-6 bytes!

If you are using MySQL 4.1 or above you can set the database to use UTF-8. Please read more here:

http://dev.mysql.com/doc/refman/4.1/en/charset-unicode.html

If you are not using MySQL (or any other DB) that supports UTF-8 you have to consider this workaround:

As long as a database does not support utf-8 so varchar(10) means “store 10 utf-8 characters regardless of bytelength” we offer a setting in TYPO3 which takes care of it:

$TYPO3_CONF_VARS[’SYS’][’multiplyDBfieldSize’] = ‘3’;

This setting will automatically change all varchar(10) fields to “varchar(30)”. After changing this setting you mustuse the Install Tool, “Database Analyzer” to alter all fields in tables.

2.2 Setting up languages

Next, you must set up which languages you want the site localized to. These languages are additional to the “default”language of the site. What the default language is will be up to you to define.

The system languages are added on the root level of the page tree. In this guide I have added two languages, Danishand Russian.

The record for the Danish language record looks like this:

When you want to localize pages and contentin TYPO3 you will now have the option between “Default”, “Danish” and “Russian”. Here is a view from theWeb>List module:


http://dev.mysql.com/doc/refman/4.1/en/charset-unicode.html

Chapter 2. Basic setup of a localized website

2.3 Defining the ‘‘default’’ language flag

If you want to specify the name of the default language and a flag icon you can do so for a branch of the page treeby setting this Page TSconfig for the root page of your website:

If you want to specify the name of the default language and a flag icon you can do so for a branch of the page treeby setting this Page TSconfig for the root page of your website.

TSConfig:

mod.SHARED {defaultLanguageFlag = gb.gif

defaultLanguageLabel = English}

This setting is for example used by the Web>Page module, Web>List and TemplaVoilà Page module.

2.4 Translations of pages

When you want a translation of a page in the page tree you create an “Alternative Page Language” record on thatpage. This contains fields similar to that of the page record which you fill in with translated content:

When such a record exists you can translate the content of the page to the language it defines. There are variousmethods to translate the content of pages and I will get back to that. The Alternative Page Language record isimportant to understand first since these define which pages has a translation and which not.

In the Web>List module they look like this:

2.3. Defining the ‘‘default’’ language flag 7


2.5 Localization Overview of the page tree

You can get a complete overview of the pagetree and according translations by using the Web>Info module, choosing the function menu item “LocalizationOverview”:

All the green entries show which languages each page is available in. The gray areas means no translation isavailable but access to the page specifying this language will be tolerated. It is also very quick to create newtranslations from this module (using the check boxes).

2.5.1 Hiding pages if no translation exist

If a translation of a page does not exist it will by default still appear in the website menu when using that language.Here the “Contact” page is still shown with default, English content:

If you check the “Hide page if no translation for current language exists” checkbox forthe “Contact” page in “page properties” you can avoid this:

This will be reflected in the Localization Overview:

From this it is clear that when viewing thewebsite in Russian the “Contact” page is not accessible. And the menu will reflect this since now the “Contact”page is not shown.

Trying to access the “Contact” page with the id will even show an error.



2.5.2 Hiding default translation of pages

If you want pages in only the alternative languages you must still create a default language page in the page treewhich simply acts as a placeholder. Setting this status is done by selecting the checkbox “Hide default translationof page”:

This is reflected like this in the Localization Overview:

On the website it will look like this:

Danish:

English:

Trying to access the page “Visioner” in 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 thetopic of a page or section is only relevant in one of the alternative languages. Especially if a language of the site isnot only a translation but may serve subsidiaries of a company in a local context.

2.5.3 Inverse control of hidden translations

If you prefer that all pages are hidden by default (reverse action of the “Localization Settings” check boxes) youcan set a TYPO3_CONF_VARS option:

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

The Localization Overview will reflect this immediately:

Notice, that the Localization Setting checkbox is reversed for the “Contact” page (the background above is gray,not red):

2.5. Localization Overview of the page tree 9


2.5.4 Final notes

Summary of colors in “Localization Overview”:

• Green background: Page is translated and viewable in this language. For translations it means that an activeAlternative Page Language overlay record is present (“Alternative Page Language” in Web>List module).

• 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 modefor content. Depends on configuration of “config.sys_language_mode” in your TypoScript Template. Moreinformation below.

Notice about possibly false menu items when “Localization settings” are used:

When running in default fallback mode (config.sys_language_mode = 0/blank/not set) menu generation may createfalse items because sys_language_uid will be different from the value set by the &L parameter (which the menuwill just pass through not knowing what it does) when a page translation is not found. Menu items not available inthe default language will not be shown even if they should and items which are not available in the translation willbe shown regardless of this.

Solution is to configure in TypoScript “config.sys_language_mode = content_fallback” because it will keep the“sys_language_uid” value according to that defined by &L regardless of whether a translation exists or not.

If you wish not to use “config.sys_language_mode = content_fallback” you can also choose to set the property“protectLvar” for the HMENU objects; this will correct the L-variable for those menu items which are not available.See TSref for details about that option.

2.6 Web>List localization view

In the Web>List module you can enable a localization view of the list which will provide you with buttons forlocalization of records from tables supporting localization:

The result is a view like this:

When a localization does not exist there will be an icon (“Localize to”) to click which will localize the element.

The elements can be localized only to the alternative languages on the page and since the page has only a Danish“Alternative Page Language” record (named “Ikke-cached”) you see only Danish flags. Adding a Russian translationwill add Russian icons:



2.6.1 Technical note about ‘‘Localizations’’

The “Localize to” links presented by the Web>List module, Web>Page module etc. uses the core “localize”command. This command creates a copy of the default language record, changes the language setting to therequested language and sets a reference back to the default language original. Thus the localized version is boundto the original giving the possibility of tracking translation precisely.

Behind this method there is an assumption that when localized elements are selected and presented in the frontendof a website it is done by selecting the default language element subsequently being overlaid with the alternativelanguage record if found. This means that all queries and references between records should be done with thedefault language records and localizations are just dumb overlays automatically selected and shown if available.Not only is this a more sound technical practice, it is also possible to take advantage of inheritance of contentfrom the default record; images, links, references etc. - data that you might not like to enter a second time for thelocalized record!

Taking advantage of overlays and inheritance is enabled by TypoScript config options like “con-fig.sys_language_overlay” and “config.sys_language_softMergeIfNotBlank”

2.7 TypoScript configuration

In your TypoScript template you will want to have a configuration of localization which looks something like this:

# Localization:config {

linkVars = L}[globalVar = GP:L=1]config {

sys_language_uid = 1language = dklocale_all = da_DKmetaCharset = iso-8859-1

}[globalVar = GP:L=2]config {

sys_language_uid = 2language = ru

}[global]

2.7.1 The ‘‘&L’’ variable

Although it is not a requirement to use the L-variable for localization it is highly recommended because it has beenhardcoded a large number of places to hold the uid of the sys_language record (menus / realurl / TemplaVoilà /Page module / Preview links / etc.).

The lines 1-3 configures that if the GET request variable “&L=X” is found it should be passed on to all generatedlinks.

Lines 4 and 11 are conditions which tell that if the GET variable “L” is 1 or 2 the system language (con-fig.sys_language_uid) is set accordingly (plus all other TypoScript template related settings you might want tochange for a localization). Also those conditions are the reason that caching will support and recognize a change inthe L-parameter.

Setting up the L-variable like this is the minimum requirement to make language switching work.

2.7. TypoScript configuration 11


2.7.2 config.language

(line 7 and 14) Setting this configures the system “language key” to be used for the language. This is used to selectlabels from llXML (locallang-XML) files. Setting this should make frontend plugins respond by showing labelsfrom the correct language (requires installation of the corresponding language packs).

2.7.3 config.locale_all

(line 8) Configures the locale which influences how some values from PHP is formatted in the output, e.g. datesformatted using strftime() which will then output month/day names in that language.

2.7.4 config.metaCharset

(line 9) Setting the output charset of the page to “iso-8859-1”. Means that content internally rendered in utf-8 (dueto “forceCharset” setting) is converted to “iso-8859-1” before output:

For default and Russian language:

Even if “config.metaCharset” is set to “iso-8859-1” for Russian the output will be correct since HTML-entities willbe used for glyphs which cannot be represented in the chosen language:

utf-8 (default):

iso-8859-1:

2.8 Localization mode: ‘‘config.sys_language_mode’’

The localization mode defines how the system behaves if there is no translation of a page to the language requested(ie. there is no Alternative Page Language record) . For instance: Would you like a “page not found” error? Orshould the default language be shown? Or should another of the available languages be tried first? And if so, wouldyou like the menu to stay in the selected language? These are the preferences you can obtain using this setting.

2.8.1 Overview of combinations

Localization mode is defined by the TypoScript configuration “config.sys_language_mode”.

The table below provides an overview of the combinations of language modes (config.sys_language_mode) andthe language uid (config.sys_language_uid, which is essentially defined by the input “&L=” variable in a typicalset-up).

• The first two columns displays the configured values (blue)

• The last three columns display the value of internal variables in TYPO3 plus a description of the behavior



• The settings are based on a page where:

• none of the “Localization Setting” checkboxes is set (meaning that neither default language, nor non-existingalternative languages are blocked)

• There is a Danish translation (Alternative Page Record) but no Russian translation.

• The default behavior of default language (English) and Danish translation is of course to show the translationand hence they are not interesting. These scenarios are included in the table but grayed out since they arethe same for each combination of “sys_language_mode”. The interesting rows are those where the Russianlanguage is requested.

This is how the localization overview is set for the page tested:

config.sys_language_mode

config.

sys_

language_

mode

config.sys_language_uid(set by &L)

config.

sys_

language

_uid

(set by &L)

TSFE->sys_language_uid

TSFE->

sys_

language

_uid

TSFE->sys_language_content

TSFE->

sys_

language

_content

Result

Result


[blank]



0


0

2.8. Localization mode: ‘‘config.sys_language_mode’’ 13


Result

• Content: English

• Menu: English



1


1


1

Result

• Content: Danish

• Menu: Danish



2


0


0

Result

Behaviour: All site content behaves like for the default language except “&L=2” is passed on in links and anysettings made with TypoScript conditions selecting on “GP:L” will take effect.


• Menu: English

• Warning: “Localization Settings” for pages are not observed correctly! See more info where “LocalizationSettings” are discussed (eg. “Hide page if no translation exists”)


content_fallback



0


0

Result


• Menu: English



1




1


1

Result

• Content: Danish

• Menu: Danish



2


2


0

Result

Behavior: Content displayed in default language while menus are rendered in Russian. This mode lets the user“stay” in the selected language, even when visiting pages that has no translated content and falls back to defaultcontent.


• Menu: Russian


content_fallback : 1,0



0


0

Result


• Menu: English



1


1


1

Result

• Content: Danish

• Menu: Danish





2


2


1

Result

Behavior: Like the setting “content_fallback” but the added values “1,0” means that the content displays first looksfor content in the language “1” (in this case Danish) and shows that if available, otherwise looks for content inlanguage “0”.

Of course it makes no sense to display Danish instead of Russian, but in cases like Portuguese/Brazil Portuguese itmight make sense to define such a second priority language.

• Content: Danish

• Menu: Russian


strict



0


0

Result


• Menu: English



1


1


1

Result

• Content: Danish

• Menu: Danish



2


•




•

Result

Error message: “Page is not available in the requested language (strict).”


ignore



0


0

Result


• Menu: English



1


1


1

Result

• Content: Danish

• Menu: Danish



2


2


2

Result

Behavior: Doesn’t consider if there is an Alternative Page Record or not for the language, just sets the value.

• Content: Russian (nothing shown of course)

• Menu: Russian



A few additional technical notes:

• Regardless of localization mode the “&L=” variable is always passed on in links (due to “config.linkVars”)

• Any TypoScript conditions (for example “[globalVar = GP:L=1]”) are still effective so any settings there arekept regardless of localization mode

• When saying “a translation exists” it is meant that an “Alternative Page Language” record exists (greenbackground in Localization Overview in Web>Info). This, however, does not refer to whether or not contentelements are localized for the page yet. However, it is generally assumed that if an Alternative Page Languagerecord has been created, so has translated content.

• Generally, the internal values TSFE->sys_language_uid and TSFE->sys_language_content maintains differ-ent functions:

• TSFE->sys_language_uid defines the overall language that content should be displayed in. This affectstemplates in TemplaVoilà, menu generations etc.

• TSFE->sys_language_content defines the language of the page content and may be different, especially thisis what makes it possible to request content from another language than that of TSFE->sys_language_uid

• If the “Localization Setting” of the page is set to “Hide default translation of page” then it will fail whenused with content_fallback and if content_fallback tries to get content from the default language.

2.8.2 Best-practice localization mode

It is recommended to use

config.sys_language_mode = content_fallback

This is so, because the compatibility with other localization functions are greatest in this case since the “TSFE->sys_language_uid” value is set to that of the requested language.

2.9 llXML (locallang-XML) in plugins and TypoScript

2.9.1 Using llXML labels in TypoScript structures

llXML files are XML files containing labels that the system can fetch in a localized version if a language pack isinstalled. If you want to retrieve values from llXML files in TypoScript you can do it like this:

page.20 = TEXTpage.20.stdWrap.data = LLL:EXT:indexed_search/pi/locallang.xml:submit_button_label

This looks for the label “submit_button_label” in the file “pi/locallang.xml” from the extension “indexed_search”.

If the “config.language” value is set to “dk” and the Danish language pack is installed in “typo3conf/l10n/dk/”the output should be “Søg” (and not “Search” which is what you will get if the label is retrieved from the defaultlanguage).

2.9.2 Using llXML labels in frontend plugins

How to use llXML labels in your PHP code is not covered in this guide (see “Inside TYPO3”), but properly madefrontend plugins will use llXML files with the plugins to generate translated labels for their output.

For instance, if “config.language = dk” and the Danish language pack is installed you will see this page for “indexedsearch”:



You can use TypoScript to overridewith custom values (supported by most extensions made by kickstarter and using the piBase API). Here is anexample for how the search button label can be overridden:

plugin.tx_indexedsearch._LOCAL_LANG.dk.submit_button_label = SØØG!

This yields this output:

You must look into the file “indexed_search/pi/locallang.xml” to know that the label key was “submit_button_label”and of course “dk” is the language key. The prefix “plugin.tx_indexedsearch._LOCAL_LANG” is exposed usingthe TypoScript Object Browser:

2.9.3 Providing a translation to a frontend plugin for a language key not found in thesystem?

There is an unfortunate binding between the system languages of TYPO3 (those you can select for the backendusers) and the translations of frontend extensions. As long as you are making a website in a language supported inthe backend you just install the language pack and you are done. But what if we wanted to make a translation of thesite to “Marsian”?

Well, we can actually do that using the “_LOCAL_LANG” overriding feature!

So a setup like this will translate the search button label to “Marsian”:

config.language = marsian

plugin.tx_indexedsearch._LOCAL_LANG.marsian {submit_button_label = !"#C%&/(

}|img-31|

2.10 Language Selector Menu

You probably want to have a website language selector menu somewhere on your website. This menu should showan entry for each possible language and since you might not have a translation for each page you might like the

2.10. Language Selector Menu 19

menu items to appear in 4 variants:

• Translation exists

• Translation exists - currently selected

• Missing translation

• Missing translation - currently selected

The way to make such a menu is to use the HMENU cObject from TypoScript and use the special type “language”.

Here is example configurations:

2.10.1 GMENU example

## Localization menu:lib.langMenu = HMENUlib.langMenu {

special = languagespecial.value = 0,1,2special.normalWhenNoLanguage = 01 = GMENU1.NO {

XY = [5.w]+4, [5.h]+4backColor = white5 = IMAGE5.file = EXT:cms/tslib/media/flags/flag_uk.gif || EXT:cms/tslib/media/flags/flag_dk.gif || EXT:cms/tslib/media/flags/flag_fr.gif5.offset = 2,2

}

1.ACT < lib.langMenu.1.NO1.ACT=11.ACT.backColor = black

1.USERDEF1 < lib.langMenu.1.NO1.USERDEF1=11.USERDEF1.5.file = EXT:cms/tslib/media/flags/flag_uk_d.gif || EXT:cms/tslib/media/flags/flag_dk_d.gif || EXT:cms/tslib/media/flags/flag_fr_d.gif1.USERDEF1.noLink = 0

1.USERDEF2 < lib.langMenu.1.USERDEF11.USERDEF2.backColor = green

}

2.10.2 TMENU example

lib.langMenu = HMENUlib.langMenu {

special = languagespecial.value = 0,1,2special.normalWhenNoLanguage = 01 = TMENU1 {

# Normal link to language that exists:NO = 1NO.allWrap = |*| | * |*| |NO.linkWrap = |

NO.stdWrap.setCurrent = English || Danish || RussianNO.stdWrap.current = 1

# Current language selected:ACT < .NOACT.linkWrap = | 

# Language that is NOT available:USERDEF1 < .NOUSERDEF1.linkWrap = | USERDEF1.doNotLinkIt = 1

}}

2.10. Language Selector Menu 21

CHAPTER

THREE

LOCALIZED CONTENT

The topic of localizing the actual content of pages is where different paradigms and preferences may step in. Oneclear difference is whether you want to localize or translate a page.

• If you wish you translate a page 1:1you might like to using “content binding” which secures exactly that. Thepage’s content is then always defined by the default language records and any translation is solely dependingon whether a localized record for the default language record exists. This is the least flexible method butleaves less room for errors.

• If you wish to localize a page you can build up a separate set of content elements for the page in their ownorder. You can still maintain references between original and translation if you wish. Most flexible, but couldbe too much freedom.

Now you will learn about the differences of these approaches in the context of the classic Page module.

3.1 Content binding

When working with the classic column based content delivery in TYPO3 (Web>Page module) you have the choiceof two different localization approaches:

• No binding: Each language can have varying number of content elements in their own order and possiblywithout a relation to any default language element.

• Binding to default language: All translations follow the elements of the default language 1-1

The modes are described visually here:

3.1.1 No binding

This is the default situation. No additional configuration of the backend or frontend is needed.

The Web>Page module has a view like this:

23


As you can see, there are three Danish elements and only two default elements.

The translations all have the language setting set to Danish (seen by the Danish flag) but may or may not have arelation to “Transl. Orig”:

If there is a “Transl.Orig” value it will be used to display what the default language content is (useful for translators):

The website displays the content like this:


Chapter 3. Localized content

3.1.2 Binding

Binding translations to follow the default language translations requires a configuration of both frontend andbackend:

• Web>Page: The page module must know that a translation must be bound 1-1 to the default translation. Thisis configured by setting “mod.web_layout.defLangBinding = 1” in Page TSconfig.

• TypoScript: You must ask the frontend rendering to select content from the default language and look foroverlay records from the translation. This is configured with “config.sys_language_overlay = 1” in theTypoScript Template.

In the Web>Page module this is reflected like this:

3.1. Content binding 25


Notice how the elements in the “Danish” column is aligned in rows bound to each element in the Default column.For the element in the middle there turn out to be no Danish translation at all.

The binding from the Danish element to the Default element is done with the “Transl. Orig” field which plays acrucial role now.

You can also notice that for each default element a localization button “Copy default content elements” will preparea record ready for Danish translation.

In the frontend the result looks like this:

You see to the right how the top and button element is displayed in the Danish translation while the middle elementis displayed in the default original since no translation exists.

Conclusion is: With content binding it is the default elements which decide over the element order and appearanceon the page.

3.1.3 Overlay modes

When using the overlay mode you can choose a few variants:

config.sys_language_overlay = hideNonTranslated

This will change the output to this:



As you can see, the element that was not translated is simply not displayed in the default language.

Another one is this setting:

config.sys_language_softMergeIfNotBlank = tt_content:image, tt_content:header

This setting will look if the “image” and “header” fields of translations are blank and if that is the case the value ofthe default language record is allowed to be used.

Since the translation of the lower element has no images entered, the image field is blank and the images from thedefault element is used instead:

So with this setting you can inherit values from the original record (default language) by leaving a field blank -or provide a translation (like for the “header” field which had a value in the translation: “[Translate to Danish:]Nullam fermentum...”).

Notice: If the “l10n_mode” for columns in TCA is set to “exclude” or “mergeIfNotBlank”, inheritance ofvalues from default records is already happening. But since you might like to enable this on a per- site basis,“config.sys_language_softmergeIfNotBlank” has been provided to add the “mergeIfNotBlank” setting to additionalfields from the template record.

If you are designing a database table for localization you should look closer at the “l10n_mode” setting fromTCA. You should also consider that when using the core localization features, references between records shouldideally be between the default language records and never to the translations themselves; translations should beselected and overlaid default language records during rendering (assuming “config.sys_language_overlay” is set).Inheritance of field values from the original record will also happen only when a translation is shown throughselecting its default language original and applying the translation over it.

3.1.4 Elements with language ‘‘[All]’’

When using language binding combined with “config.sys_language_overlay = hideNonTranslated” there is a specialsignificance of the language value “[All]” (technically the -1 value): These elements will not be hidden in thetranslation - and they are not meant to be translated although you can choose to do so.

The setting looks like this:

It is reflected in the Web>Page module like this (notice the flag):

3.1. Content binding 27

Typical applications of the “[All]” language is for “Insert Record”, “Plugin” elements (placeholders for somethingelse) or “Flexible Content Element” (“templavoila” extension, typically having localization enabled in the FlexFormcontent).

3.1.5 Notes

• ” Hide default translation of the page” incompatible with content binding: When using the “Binding”method (ie. “config.sys_language_overlay = 1 / hideNonTranslated”) you must supply placeholder records inthe default language if you use the “Localization setting” for pages “Hide default translation of the page”.

• Support for content binding: The TypoScript cObjects CONTENT and RECORD both supports the“sys_language_overlay” setting by selecting default language elements and overlaying according to thesetting. This should be observed anywhere else content is selected (like in extension plugins). Technically,the function $GLOBALS[’TSFE’]->sys_page->getRecordOverlay() does this, but before using it, pleaselook at how it has been used inside a class like “class.tslib_content.php” from the “cms” extension (tslib/)

• ” Search” content elements: “Search” content elements should be thought carefully about since they shouldsearch in the chosen language. The search query executed with the “SEARCHRESULT” cObject takes“sys_language_uid” into the query. Therefore the best is to create a search form element for each language(that is; do not inherit it). Alternatively let the search form reside on a page which is not translated at all(provided that “content_fallback” is used!)

3.2 FlexForms

FlexForms has the interesting capability of being able to store localizations internally in its XML. Whether this isenabled or not depends on the <meta>-tags in the Data Structure. But a prerequisite is that an ISO-code has beenassociated with the system languages:

(This requires “static_info_tables”).

Where localized content in TYPO3 identifies its language by a uid- value (the content of [languageField]) pointingto a “Website Language” record, flexforms use the universal ISO-code which is a newer and better architecture ofcourse.

In the following the FlexForm localization modes are described. They apply universally to FlexForms but toillustrate the usage they are described in the context of a TemplaVoilà based website and in relation to “FlexibleContent Elements”. This is far the most typical application of FlexForm fields carrying localized content. Otherapplications are for Plugin configuration but in this case you will most likely disable localization all together.

3.2.1 FlexForm Localization modes

There are three localization modes possible for FlexForm content:

• Disabled: No inline localization of the element.

• Inheritance: Each default value in the FlexForm can be translated 1-1. Thus the translation closely followsthe default language. This also allows for inheritance of default language values (like link values or images)

• Separate: Each localization of the element can have a separate structure. This is only relevant if the flexformelement provides deep structures like link lists which must be different in each language.

These modes are configured by the <meta> tag in the Data Structure.

As soon as you have begun using a Data Structure you cannot switch between Inheritance and Separate (<langChil-dren> = 1/0) without loosing localized content. However default content is never lost. (There might exist tools tomake this conversion for you).

3.2.2 Overview

This overview shows the possible localization modes for a FlexForm field.

Where a FlexForm field is used to store references to content elements - called “container elements” - additionalconsideration especially related to TemplaVoilà applies. For a discussion of this, please refer to subsequent chapters.

a

Disabled

Disabled

Inheritance

Inheritance

Separate

Separate

a

Description:

Disabled

No inline localization of the element.

Inheritance

Each default value in the FlexForm can be translated 1-1. The translations follows the default language.

Separate

Each localization of the element can have a separate, independent structure. Translation has no technical relation todefault language.

a

Usage:

Disabled

Universal: For all languages

Inheritance

Translation: Default content is faithfully translated 1-1 in each language.

Separate

Localization: Content in other languages can divert from the structure of the default language

a

Record language

(“languageField” value)

Disabled

Use: [All] language

3.2. FlexForms 29

Alternatively you can of course localize the record with the core supported localization like any other record.

Inheritance

Use: [All] language

Separate

Use: [All] language

a

Data Structure configuration:

Disabled

<meta>

<langDisable>1</langDisable>

</meta>

Notice: <langChildren> is insignificant in this case.

Inheritance

<meta>

<langChildren>1</langChildren>


</meta>

Separate

<meta>

<langChildren>0</langChildren>


</meta>

a

Inheriting default content:

Disabled

Not Applicable

Inheritance

Default content is inherited if there is no translated content (“blank” string or zero).

Configurations apply, see later

Separate

Not possible since there is no technical relation between localized content.

a

Recommended usage:

Disabled

Use this type for FlexForm fields working as “container elements” providing structures for other content elements.In such cases it is unlikely that you want localization of the content element references(*).

Could also be Plugin configuration (also independent of language)

Recommended for container elements!

Inheritance


Recommended typesince most websites only need a 1-1 translation of content. In cases where certain elementsshould be ignored in the translation there are ways to work around that.

Recommended for content!

Separate

Could be considered for Data Structures with substructures of sections/arrays (like the link list below) but for anyData Structure with only a single level you should avoid this type since its less flexible.

Avoid, unless expert

a

Warnings:

Disabled

Inheritance

• Be careful if using them as “container elements”

Separate

• Never use as “container element”

a

Special notice related to “Free” paradigm (see later) and container elements

Disabled

In the “Free” paradigm, “Disabled” usually indicates that no localization is intended for a container element. Thisis opposite to the “Bound” paradigm where “Disabled” is the recommended mode.

The reason is that the “Free” paradigm doesn’t expect localization overlays of default language records but ratherbase itself on building separate structures of localized elements, hence needing either “Inheritance” or “Separate”modes. However, there are some flaws which makes that paradigm problematic. Please refer to discussion later.

Inheritance

In the “Free” paradigm, this mode is recommended since a separate structure of content elements is built. However,as a content structure grows deeper than a single level this makes it impossible to keep the order in sync with thedefault language since that will be located in another element.

Separate

See note for “Inheritance” mode, same applies.

In the following each type will be illustrated:

3.2.3 Disabled

This is a FlexForm element with localization disabled. It appears under the exact same terms as any other contentelement does: Based on its language setting in the field defined by “[languageField]” (see later).

Since this Data Structure is used to display the differences between localization modes lets take a look at it:

• There is a Header and Body field on the root level

• Then, there is a link section where we can add zero to many items, which in turn lets us choose between theitem type “Link header” (single field) or “Link” (header + url field)

3.2. FlexForms 31


In the output on the page it looks like this:

3.2.4 Inheritance

With Inheritance the translation is included closely bound to the default value. In the FlexForm it looks like this:

Notice that for each field (“Header”) you find a counterpart for the available languages (“Header (vDA)”).

The code indicating the language (“vDA”) is a “v” + language ISO code.

Notice that the field “Url (vDA)” for the second link is blank. When this is the case the value from the “Url” field(default value) is inherited. This can be useful for such as URLs which doesn’t change between languages - ormight just change in which case you can optionally supply them!

The website display of the default record is this:



The danish display is this:

As you can see the text is translated. Only a mouse-over or click on the second link will show that the URL isinherited - but trust me, it is ;-)

3.2.5 Separate

In the “Separate” mode the two languages are separated completely in the form. This doesn’t make any differencefor the “Header” and “Body” fields but the “Link section” can be composed differently in the two languages. Belowit is very easy to see this difference because for the Danish translation (“DA”) there is only one “Link” entrycontrary to the “Link header” / “Link” / “Link” composition of the default language.

The result on the website is as expected.

First the Default display:

3.2. FlexForms 33

Then the Danish “localization”:

This is the flexibility of the “Separate” approach - that you can truely localize you content, not just translate it. Butthe price is that the relation between the default and translated content is lost in a technical sense.

3.2.6 FlexForm Data XML

The following is quite technical but for those who wish to take a look at how the FlexForm XML data is different ineach scenario you can compare these listings:

‘‘Disabled’’:

1: <?xml version="1.0" encoding="utf-8" standalone="yes" ?>2: <T3FlexForms>3: <data type="array">4: <sheet index="sDEF" type="array">5: <language index="lDEF" type="array">6: <field index="field_header" type="array">7: <vDEF>Localization: Disabled</vDEF>8: </field>9: <field index="field_body" type="array">

10: <vDEF>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras id quam ut sem ullamcorper aliquam. Aliquam faucibus urna sit amet massa. Quisque rutrum enim sed libero mollis fringilla. Maecenas eget sapien ac est vehicula ullamcorper. Aenean nunc tellus, sollicitudin id, ornare nec, euismod non, nunc. Sed aliquam, pede eu suscipit posuere, elit quam facilisis neque, vel dignissim arcu lacus at nulla.</vDEF>11: </field>12: <field index="field_links" type="array">13: <el type="array">14: <field index="1" type="array">15: <field_linkheader type="array">16: <el type="array">17: <field index="field_headerstr" type="array">18: <vDEF>Maecenas eget</vDEF>19: </field>20: </el>21: </field_linkheader>22: </field>23: <field index="2" type="array">24: <field_linkcontent type="array">25: <el type="array">26: <field index="field_linktext" type="array">27: <vDEF>My link to TYPO3.org</vDEF>28: </field>29: <field index="field_url" type="array">30: <vDEF>http://typo3.org/</vDEF>31: </field>32: </el>33: </field_linkcontent>34: </field>35: <field index="3" type="array">36: <field_linkcontent type="array">37: <el type="array">38: <field index="field_linktext" type="array">39: <vDEF>My link to TYPO3.com</vDEF>40: </field>41: <field index="field_url" type="array">42: <vDEF>http://typo3.com/</vDEF>43: </field>

44: </el>45: </field_linkcontent>46: </field>47: </el>48: </field>49: </language>50: </sheet>51: </data>52: </T3FlexForms>

‘‘Inheritance’’:

1: <?xml version="1.0" encoding="utf-8" standalone="yes" ?>2: <T3FlexForms>3: <data type="array">4: <sheet index="sDEF" type="array">5: <language index="lDEF" type="array">6: <field index="field_header" type="array">7: <vDEF>Localization: Inheritance</vDEF>8: <vDA>Danish alternative header (Localization: Inheritance)</vDA>9: <vRU></vRU>

10: </field>11: <field index="field_body" type="array">12: <vDEF>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras id quam ut sem ullamcorper aliquam. Aliquam faucibus urna sit amet massa. Quisque rutrum enim sed libero mollis fringilla. Maecenas eget sapien ac est vehicula ullamcorper. Aenean nunc tellus, sollicitudin id, ornare nec, euismod non, nunc. Sed aliquam, pede eu suscipit posuere, elit quam facilisis neque, vel dignissim arcu lacus at nulla.</vDEF>13: <vDA>Danish alternative bodytext here. Maecenas eget sapien ac est vehicula ullamcorper. Aenean nunc tellus, sollicitudin id, ornare nec, euismod non, nunc. Sed aliquam, pede eu suscipit posuere, elit quam facilisis neque, vel dignissim arcu lacus at nulla.</vDA>14: <vRU></vRU>15: </field>16: <field index="field_links" type="array">17: <el type="array">18: <field index="1" type="array">19: <field_linkheader type="array">20: <el type="array">21: <field index="field_headerstr" type="array">22: <vDEF>Maecenas eget</vDEF>23: <vDA>Danish header</vDA>24: <vRU></vRU>25: </field>26: </el>27: </field_linkheader>28: </field>29: <field index="2" type="array">30: <field_linkcontent type="array">31: <el type="array">32: <field index="field_linktext" type="array">33: <vDEF>My link to TYPO3.org</vDEF>34: <vDA>Mit link til TYPO3.org</vDA>35: <vRU></vRU>36: </field>37: <field index="field_url" type="array">38: <vDEF>http://typo3.org/</vDEF>39: <vDA>http://typo3.org/dk/</vDA>40: <vRU></vRU>41: </field>42: </el>43: </field_linkcontent>44: </field>45: <field index="3" type="array">46: <field_linkcontent type="array">47: <el type="array">48: <field index="field_linktext" type="array">49: <vDEF>My link to TYPO3.com</vDEF>

3.2. FlexForms 35

50: <vDA>Mit link til TYPO3.com</vDA>51: <vRU></vRU>52: </field>53: <field index="field_url" type="array">54: <vDEF>http://typo3.com/</vDEF>55: <vDA></vDA>56: <vRU></vRU>57: </field>58: </el>59: </field_linkcontent>60: </field>61: </el>62: </field>63: </language>64: </sheet>65: </data>66: </T3FlexForms>

‘‘Separate’’:

1: <?xml version="1.0" encoding="utf-8" standalone="yes" ?>2: <T3FlexForms>3: <data type="array">4: <sheet index="sDEF" type="array">5: <language index="lDEF" type="array">6: <field index="field_header" type="array">7: <vDEF>Localization: Separate</vDEF>8: </field>9: <field index="field_body" type="array">

10: <vDEF>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras id quam ut sem ullamcorper aliquam. Aliquam faucibus urna sit amet massa. Quisque rutrum enim sed libero mollis fringilla. Maecenas eget sapien ac est vehicula ullamcorper. Aenean nunc tellus, sollicitudin id, ornare nec, euismod non, nunc. Sed aliquam, pede eu suscipit posuere, elit quam facilisis neque, vel dignissim arcu lacus at nulla.</vDEF>11: </field>12: <field index="field_links" type="array">13: <el type="array">14: <field index="1" type="array">15: <field_linkheader type="array">16: <el type="array">17: <field index="field_headerstr" type="array">18: <vDEF>Maecenas eget</vDEF>19: </field>20: </el>21: </field_linkheader>22: </field>23: <field index="2" type="array">24: <field_linkcontent type="array">25: <el type="array">26: <field index="field_linktext" type="array">27: <vDEF>My link to TYPO3.org</vDEF>28: </field>29: <field index="field_url" type="array">30: <vDEF>http://typo3.org/</vDEF>31: </field>32: </el>33: </field_linkcontent>34: </field>35: <field index="3" type="array">36: <field_linkcontent type="array">37: <el type="array">38: <field index="field_linktext" type="array">39: <vDEF>My link to TYPO3.com</vDEF>40: </field>41: <field index="field_url" type="array">

42: <vDEF>http://typo3.com/</vDEF>43: </field>44: </el>45: </field_linkcontent>46: </field>47: </el>48: </field>49: </language>50: <language index="lDA" type="array">51: <field index="field_header" type="array">52: <vDEF>Danish alternative header (Localization: Separate)</vDEF>53: </field>54: <field index="field_body" type="array">55: <vDEF>Danish alternative bodytext here. Maecenas eget sapien ac est vehicula ullamcorper. Aenean nunc tellus, sollicitudin id, ornare nec, euismod non, nunc. Sed aliquam, pede eu suscipit posuere, elit quam facilisis neque, vel dignissim arcu lacus at nulla.</vDEF>56: </field>57: <field index="field_links" type="array">58: <el type="array">59: <field index="1" type="array">60: <field_linkcontent type="array">61: <el type="array">62: <field index="field_linktext" type="array">63: <vDEF>Danish link to a completely other site</vDEF>64: </field>65: <field index="field_url" type="array">66: <vDEF>http://joomla.org/</vDEF>67: </field>68: </el>69: </field_linkcontent>70: </field>71: </el>72: </field>73: </language>74: <language index="lRU" type="array">75: <field index="field_header" type="array">76: <vDEF></vDEF>77: </field>78: <field index="field_body" type="array">79: <vDEF></vDEF>80: </field>81: </language>82: </sheet>83: </data>84: </T3FlexForms>

Conclusion:

The interesting difference is that for “Inheritance” you find the translation of the default value (<vDEF>) in a tagon the same level in the XML (e.g. “<vDA>”) - all within the <language index=”lDEF”> tag. With “Separate” youfind the translation in a separate structure under <language index=”lDA”> while all values are stored with <vDEF>.In both cases the default language content is stored in the same way.

This also tells you why you cannot switch between the two types when you have first added localized content: Youwill simply loose it since TYPO3 will look for the translation of content in another position in the XML. Theremight be tools that can re-map the content for you if you need to make this change.

3.2.7 Language access control

If a translator is restricted to a single language (here: Danish) then the flexform will display only that/thoselanguages - and the default language content (to be translated) is displayed read-only:

3.2. FlexForms 37


3.3 FlexForm - Containter Elements

A “Container Element” refers to a Flexible Content Element which has one or more fields on root level wherereferences to other content elements can be placed. Typically such elements are used to create zones in a grid wherecontent can be placed, thus they serve a structural purpose.

A classic container element could be a 2-column element, here named “Curabitur venenatis...” having a “Leftcolumn” and “Right column”:

In each column you see another content element placed.

On the website it looks like this:

Notice that container elements usually must have the “[All]” language set so they are rendered for all languages:



3.3.1 Two paradigms of using container elements

Unfortunately, two different approaches to localizing a website with container elements have developed. InsideTemplaVoilà’s Page module we had to implement support for both.

By default TemplaVoilà follows the “Bound” paradigm which is the recommended mode taught by this documentwhile the “Free” paradigm must be configured via Page TSconfig in order to be reflected in TemplaVoilà’s Pagemodule.

This is the difference:

• ” Bound” paradigm (default, recommended): Promotes that the structure (order and nesting) of contentelements on a page should be the same for all languages. Consequently, all container elements shouldhave data structures where localization mode is “Disabled”. All content carrying elements (such as “Text& Images”) is placed as default language elements which can have overlaid localizations (requiring “con-fig.sys_language_overlay” to be set). Elements unique to a language can be placed separately if neededand in the rare case where a separate page structure is required, “Inheritance” mode could be used for thecontainer element DS.

• ” Free” paradigm (alternative, configurable): Promotes that the structure (order and nesting) of contentelements is build separately for each language, using either “Inheritance” or “Separate” mode in the datastructure. While this may seem natural it imposes lots of problems; the core localization features are usedin a less optimal way excluding the possibility of content inheritance; elements can be ordered differentlywhich would usually be a mistake; content structures deeper than a single level is impossible to synchronizetechnically.

The “Free” paradigm is configured by setting this line in Page TSconfig:

mod.web_txtemplavoilaM1.translationParadigm = free

The bottom line is that the “Bound” paradigm is the most flexible with the least complexity. Therefore this documentpromotes this solution. In the following I will try to notify where the difference between the two is necessary tokeep in mind.

3.3.2 Localization mode of Container Elements (‘‘Bound’’ paradigm)

When using Container Elements under the “Bound” paradigm (default and recommended) you should never use“Separate” mode, you should avoid “Inheritance” since it can confuse and the preferred mode is “Disabled” .

This recommendation is based on the assumption that most multilingual websites basically want to translate pagesto other languages and therefore want the same order and hierarchy of content elements for each language. For thispurpose “Disabled” mode for container elements is the way to go since that will ensure that the page structure isbuilt by the same content elements regardless of language (localizations of content carrying elements are suppliedas overlays).

However, you might like that some pages on your website could look entirely different in another language. Maybeyou want two columns and five elements in the bottom for some reason. In such cases you have moved fromtranslating the page to localizing the page. If this is a need of yours you should select the “Inheritance” modebecause it gives you this flexibility. Basically; by default it will inherit the default structure for all languages unlessyou explicitly choose to implement one or more languages with their independent structure.

If you are really radical and want all pages in alternative languages to have its own structure built you can use the“Separate” mode, but my opinion is that you should probably have chosen not to use the “one-tree-fits-all” paradigmof localization then! If you want so radically different a website chances are good that you should have built acompletely separate site for that language then! Otherwise you will find that all these nice localization techniquesmostly work against you and not with you.

3.3.3 Localization mode of Container Elements (‘‘Free’’ paradigm)

When using Container Elements under the “Free” paradigm it only makes sense to use “Inheritance” or “Separate”modes.

3.3. FlexForm - Containter Elements 39

Each translation of the page is built by placing content elements in the container for that particular language.Usually you will try to place localizations of the default language records in the separate structure. If you configureTemplaVoilà’s Page module with “mod.web_txtemplavoilaM1.translationParadigm = free” in Page TSconfig youwill obtain support for this since the link to localize a record will not only create a localization but also place areference in the container field.

3.3.4 Localization mode of Container Elements (Advanced details for ‘‘Bound’’ paradigm)

Here is a more in-depth and technical description:

Separate mode:

In “Separate” localization mode (<langChildren>0</langChildren>) the fields containing the relations to thelocalized content elements are separate from the default language fields:

What it means is that if you want any elements to appear in Danish you will have to create relations in the twoDanish fields. TemplaVoilà’s page module supports this when you switch the “Show page language version” to thedesired language. But experience shows that users will be puzzled why nothing is shown for Danish! This is onlyuseful for building separate structures of content elements.

So altogether the “Separate” localization mode for Flexible Content Elements with container fields is discouraged.

In the Web>TemplaVoilà control center you will see all Data Structures with this problem marked with a warning(if “Show Details” is enabled).

In the TemplaVoilà page module you will also see the warning:

Notice: If “Free” paradigm is enabled with “mod.web_txtemplavoilaM1.translationParadigm = free” thesewarnings are removed and references to localizations are created automatically for you, thus making this modeusable, however not exempt from its theoretical problems.

Inheritance mode:

In “Inheritance” localization mode (<langChildren>1</langChildren>) the fields containing the relations to thelocalized content elements are bound to the default language fields:

Since inheritance of values is enabled by default (gray arrows) this will work because values are also used forDanish rendering. But - if a user adds a relation to any of the Danish fields that relation is used instead (as expected)but TemplaVoilà will only reflect this in the Page module if that language is selected (in “Show page languageversion”). This could be confusing for users.

Here, you can see how the view for the default language looks:

And here is the view for the Danish language selected:

On the website for the Danish page you will see a funny mix because the left column will contain the rendering ofthe element “Fusce adipiscing...” specifically set for the Danish view while the right column inherits the referenceto the element “Universal content”.

3.3. FlexForm - Containter Elements 41

In the TemplaVoilà control center a warning is shown for container elements with “Inheritance” mode:

In the TemplaVoilà page module you will alsosee a warning:

In case you use “Inheritance” on purpose for your container elements you can disable this warning using PageTSconfig:

mod.web_txtemplavoilaM1.disableContainerElementLocalizationWarning_warningOnly = 1

Cases where you might use “Inheritance” for container elements is if such elements also contains regular inputfields which needs localization.

Notice: If “Free” paradigm is enabled with “mod.web_txtemplavoilaM1.translationParadigm = free” thesewarnings are removed and references to localizations are created automatically for you, thus making this modeusable, however not exempt from its theoretical problems.

Disabled mode:

In “Disabled” localization mode (<langDisable>1</langDisable>) the fields containing the relations to the localizedcontent elements are used regardless of language! This means that it is the same relations - those of the defaultlanguage and shown by the TemplaVoilà page module - which is used for all languages and with no possibilities ofconfusion!

It looks like this:

In the TemplaVoilà control center you see no errors or warnings:

Notice: If “Free” paradigm is enabled with “mod.web_txtemplavoilaM1.translationParadigm = free” localizationis not possible since the “Free” paradigm expects to build separate structures of content elements for each language.

3.3.5 Working with ‘‘Inheritance’’ and ‘‘Separate’’ modes for container elements

If you choose to work with Inheritance and Separate mode for container elements you will use the “Show pagelanguage version” to switch between the views (goes for both “Bound” and “Free” paradigms):

3.4 Inheritance settings (specific for TemplaVoilà!)

The “Inheritance” localization mode of FlexForms can be modified further. It is possible to completely disableinheritance by the “dontInheritValueFromDefault” property of the tx_templavoila_pi1” plugin. For content elementsthis can be done with

plugin.tx_templavoila_pi1.dontInheritValueFromDefault = 1

It can also be used for TemplaVoilà page templates, typically

page.10.dontInheritValueFromDefault = 1

3.4.1 <langOverlayMode>

More advanced is the tag “<langOverlayMode>” applicable in both Data Structures and the local processing ofTemplate Objects.

With this tag you can set modes like “ifFalse”, “ifBlank”, “never”, “removeIfBlank”. The latter will enable you toexclude the display of elements if a certain field is blank, thus making up for some of the flexibility lost when usingthe “Inheritance” mode compared to “Separate”.

You must consult the TemplaVoilà documentation on the Data Structure XML for more information.

3.4.2 Advanced usage of Inheritance - an example

In this example I will show how <langOverlayMode> can be used to change number of link objects displayed forthis Flexible Content Element:

The setting we will use for “<langOverlayMode>” is “removeIfBlank” and we will apply it to the “Link text” field!With that setting this is what happens for each link:

• Link, top: Has content for both default and danish, will be shown of course.

• Link, middle: Has no content for the danish URL. This will be inherited from the default url (default setting,no effect of <langOverlayMode>)

• Link, bottom: Has no content for the danish “Link text” and that affects the whole display of that link because<langOverlayMode> is “removeIfBlank” for the “Link text” field and according to the documentation thatwill block the rendering of the whole group of fields.

Visually, this is how the default links render:

3.4. Inheritance settings (specific for TemplaVoilà!) 43

And this is how they render in Danish. Obviously the last link is missing altogether:

Where to set <langOverlayMode>?

Well, you can set it in the Data Structure (DS), but alternatively you can set it in a Template Objects (TO) “Localprocessing” field. This allows you to vary the setting based on which TO renders the DS.

The “Local processing” field looked like this:

<T3DataStructure><ROOT type="array">

<el type="array"><field_links type="array">

<el type="array"><field_linkcontent type="array">

<el type="array"><field_linktext type="array">

<tx_templavoila type="array"><langOverlayMode>removeIfBlank</langOverlayMode>

</tx_templavoila></field_linktext>

</el></field_linkcontent>

</el></field_links>

</el></ROOT>

</T3DataStructure>

Notice: If “Free” paradigm is used, FlexForm content using Inheritance or Separate modes is possible only if thesame element is used from each languages content structure. These problems are a main objection agains the “Free”paradigm because it so easily leads to confusion.

3.4.3 Limiting access to FlexForm fields for translators

Strictly, this is related to permissions, but it is interesting in the context. Consider if you wanted translators to onlydeal with the “Link text” fields of the form above, not the “Url” fields? Or it could be an image field where youwant to inherit the default image - but translators would mistakenly insert new images if they see the field is blank.Well, what you can do is use a special display condition in the Data Structure to block display of some fields fortranslators:

<TCEforms type="array"><displayCond>HIDE_L10N_SIBLINGS:except_admin</displayCond><config type="array">

<type>input</type><size>15</size>...

Now, the magic lies in “HIDE_L10N_SIBLINGS” and the added parameter “except_admin” means that admin-users will see the URL fields (thus they can set exceptional values if needed). But the point is: Any other user willsee this form with no Url fields:


3.5 Localized TemplaVoilà Template Objects

TemplaVoilà offers to select an alternative Template Object (TO)when the language is changed. What you do is to create an TO as a “Sub-template” of the main TO:

Of course you must select the correct language and then provide a mapping for this TO as well.

In the Web > TemplaVoilà module you see the sub template displayed indented with the parent TO:

The localized template is selected based on the value of TSFE->sys_language_uid

3.6 TemplaVoilà Page Module

TemplaVoilà’s page module has a tab for localization specific options:

3.5. Localized TemplaVoilà Template Objects 45


• ” Show page language version”: This defines the language used to select from the FlexForm data structure.Usually the effect will be to see Flexible Content Elements show their content preview in that language.Ifyou have container elements with localization enabled you might see an altogether different composition ofthat page! (Used especially for the “Free” paradigm)

• ” Edit language header”: Click a flag to edit the page header / Alternative Page Language record. This alsoshows the languages in which the page exists already.

• ” Create new page translation”: Select a language which the page has not yet been translated to in order tostart translation!

For the “Bound” paradigm the “Show page language version” selector may be further filtered using a control thatallows to scale down the number of languages displayed in the common structure:

3.6.1 Localization modes for a page Data Structure (‘‘Bound’’ paradigm)

Almost by definition a Page Data Structure is a “container element” because without at least one field that cancontain content elements there is not much content management to do.

As for Flexible Content Elements the most simple localization mode is the “Disabled” mode for a page DataStructure. This means the same structure of content elements is used for all languages. This is the “translation”mode where you do a 1-1 translation of the site. In the discussion for Flexible Content Elements this has beenlabeled the “Bound” paradigm. Opposite to this stands the “Free” paradigm which essentially is based on creatingseparate structures of content elements for each language.

Paradigms

I have chosen the word “paradigm” to describe the difference between these concepts because they are basicallydifferences in how you think of localization. The discussion prior to defining these paradigms also showed that itwas quite hard to tune ones brain into understanding the other paradigm. If you have a hard time to understand howthe “Bound” paradigm could ever work since it builds the pages for all languages in the “Default language” structureit is simply because you have missed a feature in TYPO3 called “content overlay” (“config.sys_language_overlay”in TypoScript). This little feature means that when a page is displayed in Danish the rendering engine first selectsthe default language elements of the page but subsequently looks for a danish translation related to the defaultlanguage element. If found, the Danish content is shown instead. If you are not familiar with that feature, of coursethe “Bound” paradigm seems like an illogical solution.

So, in the “Bound” paradigm the “Disabled” mode allows for a single content structure to be created which servesall languages.



However, you can choose the other modes as well. Lets try the “Inheritance mode”:

This will show a blank “Main Content Area”inside of which you can build a completely different page structure for the danish language. Since the Inheritanceprinciple applies, this structure will only be used if you put content element references there - otherwise the defaultlanguage structure is used.

Using the “Separate” localization mode will do the same except you will have to put in content in the Danishlanguage version, otherwise the page is blank.

a

Disabled

Disabled

Inheritance

Inheritance

Separate

Separate

a

Usage

Disabled

All pages must have exact same structure.

Inheritance

All pages will have same structure by default - but switching to another language will allow separate structures tobe built for some languages

Separate

All pages must be separately built for each language.

a

Rating

Disabled

Recommended for most projects

Inheritance

Recommended if more flexibility is needed for localization of certain pages, or if the Data Structure with thecontainer fields also needs to carry content like a background image or header text.

Separate

Most like you will not need this mode unless all pages are sure to be different in all language. But you will not looseanything by using “Inheritance”, rather gain the possibility of fallback to the default language. And further, if youcarry through that all pages must be specially localized it questions if you should have chosen the one- tree-fits-allapproach in the first place instead of making a separate tree.

a

Philosophy

Disabled

3.6. TemplaVoilà Page Module 47


Translation 1-1

*Recommended*

Inheritance

Translation / Localization (customized)

Separate

Localization (customized)

3.6.2 Element language in ‘‘Inheritance’’ and ‘‘Separate’’ modes.

When building a separate structure of content elements using “Inheritance” or “Separate” modes for a page or FCEcontainer element you strictly don’t need to tag these elements with a language. However, for two reasons you willhave to:

• If you want language access control to be enforced you will have to set the language for elements.

• If you have set up your TypoScript template with “config.sys_language_overlay = hideNonTranslated”(recommended) you will not see anything unless you tag elements with the correct language!

Here is an example. First the layout of the page/frontend in default language:

Then, how it looks with Danish language selected and in the frontend:

Notice how the page structures are very different: For the default language there were two columns, for the Danish“localized” version there was only a single content element placed directly in the “Main Content Area”.

Under normal circumstances where the localization mode of the Page Data Structure is “Disabled” (or “Inheritance”but with no elements added for the Danish page language version) you should see this view:

The reason why the page will show danish content is that the individual elements of the page are localized 1-1(“config.sys_language_overlay” is set of course in order to overlay default records with their localizations):



• The element “FCE DS: Disabled”: Container element creating two columns. Is set to the universallanguage “[All]” and will therefore be rendered regardless of selected language on the website.

• The element “Default language here...”: Normal “Text” content element that has a localized version inDanish. When the page is rendered, the default version is selected but overlaid with the danish localizationon the website (because of “config.sys_language_overlay = 1”)

• The element “Universal content”: A Flexible Content Element with a FlexForm Data Structure wherelocalization is enabled (either “Inheritance” or “Separate”) and therefore the element in itself is set to theuniversal “[All]” language since the localized content is embedded in the FlexForm data.

In case the page Data Structure had localization mode set to “Disabled” you will see no difference of the Pagemodule view when you switch “Show page language version” to Danish.

In case the page Data Structure had localization mode set to “Inheritance” you would see an empty structure whenchanging to Danish. Since the mode was “Inheritance” and the danish “Main Content Area” is blank, the danishrendering will be done with the Default language structure. But as shown above, the empty Danish structure couldbe used to build completely different structures if needed. But the recommendation is that you only do this whenstrictly needed!

What you just saw is a good case of how the “Bound” paradigm works! Notice how the localized page was buildwithout creating a separate structure of elements in the Danish “Main Content Area” but rather achieved throughbinding of localizations to their default elements.



3.6.3 Adding elements in only one language

Since for TemplaVoilà localized websites us-ing the “Bound” paradigm you must use the setting “sys_language_overlay” (unless using “Free” paradigm;building separate structures with “Separate” mode for containers) you will be able to place solo elements on a pagefor the translated languages:

This example shows a danish element which is not bound to a default language elements but appears solo on thepage. It will only be shown when the danish language is selected. So for the default display it looks like this:

The Danish display looks like this (notice the extra element in the bottom):

3.6.4 ‘‘Disable’’, ‘‘Inheritance’’ and ‘‘Separate’’ modes for containers - case study

One would think I have wasted enough time already trying to explain the details of these modes for containerelements but I will not spare you a chance to see a comparison between them in how they solve the same problem!Maybe this will visualize it a bit more how the “Bound” paradigm works.

First, take a look at how the website output looks for both default language and Danish. This view will bereproduced using the three difference approaches, representing “Bound” and “Free” paradigms.



Normal display (default language):

Two content elements are positioned side-by-side by a 2-column container element:

When ‘‘Danish’’ is selected:

In Danish the two content elements are translated but a third element has been added specifically for Danish:

Let’s take a look at how this can be achieved with TemplaVoilà using either of the localization modes for the2-column container element:

’’ Disabled’’ mode / ‘‘Bound’’ paradigm:

When the container has localization mode set to “Disabled” you will see this view for the above content. The tablealso explains how rendering progresses for English and Danish display:

Show page language version: ‘‘English’’ (Default):

• Element [1] is rendered because it has the “Default” language set.

• Element [2] is rendered because it has the “[All]” language set, thus universal

• Element [3] and [4] are not rendered - they are set to Danish



Show page language version: ‘‘Danish’’:

For Danish, the structure shown in the page module is the same as for Default because the localization mode is“Disabled” for the container element - thus all the localization is handled by the elements themselves:

• Element [1] is selected because it has “Default” language - but TYPO3 looks for a localized version (becauseof config.sys_language_overlay = 1) and finds Element [3] which is rendered (possibly with merged fieldsaccording to l10n_mode)

• Element [2] is rendered because it has the “[All]” language set, thus universal. The element is a FlexibleContent Element and we can see that it has localization enabled for its FlexForm so localization is handledinternally in the element.

• Element [3] is rendered because it has the Danish language set (this was not shown in the default display)

’’ Inheritance’’ mode / Typically ‘‘Free’’ paradigm:

If “Inheritance” mode was used for the container element you would need this structure to create the same result:







For Danish, the structure shown in the page module is different.

• Left column:

– Element [7] is meant to be a localization of Element[5] from the default view (typically created underthe “Free” paradigm), but essentially it is just an unrelated copy of that element with Danish set aslanguage. (It is considered inconsistent if this element was a true localized version of the defaultelement pointing back to it with its “transOrigPointerField”. However, that is what the “Free” paradigmdoes when the “Localize” link is clicked for a default record.).

– Element [8] is essentially Element [4] which in the “Inheritance” mode is moved to the Danish structure.

• Right column [8]

– This is empty - but because of the “Inheritance” mode it will inherit the content from default language(=Element [6]). Since Element [6] has the [All] language set it will also render for the danish view.

Interestingly, the structure from “Disabled” mode would also work as well under “Inheritance” mode. This is a greatflexibility as I have mentioned before but might be two confusing and error-prone if the users doesn’t understand it.

” Separate” mode / Only “Free” paradigm:

With “Separate” mode you will have to create these structures:


For the default language it is exactly the same as for “Inheritance” mode:






For Danish, the structure is almost similar to that of “Inheritance” mode above - except that we had to duplicate (orreference) the element [14] in the right column since no inheritance exists for “Separate” mode.

Notice: Elements [11] and [14] didn’t have to be [All], could have been Default and Danish respectively.

Notes:

For this example I used a Flexible Content Element as container element but there is no difference if the page DataStructure itself had two columns (which is probably more typical).

Also, the Page TSconfig was set to disable the warnings/errors display when container elements has localizationmode set to “Inheritance” or “Separate”:

mod.web_txtemplavoilaM1.disableContainerElementLocalizationWarning = 1

Finally “config.sys_language_overlay = 1” was set in the TypoScript Template record to enable the overlay oflocalized versions used in the “Disabled” mode.

3.7 TemplaVoilà: Best-practice

This table shows various best-practice recommendations for localized websites when using TemplaVoilà. Theassumption is that the “Bound” paradigm is used.

Topic

Topic

Recommendation

Recommendation

Topic

TypoScript Template Configuration

Recommendation



A typical, generic TypoScript configuration for setting up support for one additional language (here “dk”) lookslike this:

# Localization:config {

linkVars = Lsys_language_mode = content_fallbacksys_language_overlay = hideNonTranslated

}

[globalVar = GP:L=1]config {

sys_language_uid = 1language = dklocale_all = da_DK

}[global]

Setting “sys_language_overlay” to at least “1” is mandatory for the “Bound” paradigm and TemplaVoilà (onlycolumn based websites and the “Free” paradigm can do without) and most likely you would like to set the morestrict “hideNonTranslated” keyword which requires a record to have a translation before it can be displayed.

Topic

Page Data Structure localization mode

Recommendation

Create a page template using TemplaVoilà’s wizard. Modify the Data Structure XML so localization is “Disabled”.In rare cases you might like the ability to localize some pages with entirely different structures of content elementsin which case “Inheritance” is a good option.

Stay clear of “Separate” mode.

Topic

FCE Data Structures localization mode

Recommendation

For Flexible Content Elements you should localize them according to their characteristics:

• Pure container elements: Use “Disabled” localization mode (least complex)

• Pure hierarchical content: Use “Inheritance” localization mode (least complex, most features)

• Mixed containers and content: Use “Inheritance” localization (least complex)

Stay clear of “Separate” mode.

Always use the “[All]” language for a Flexible Content Element! See below.

Topic

“[All]” language?

Recommendation

If “sys_language_overlay” is set to “hideNonTranslated” it becomes very important that all “multilanguagerecords”like all Flexible Content Elements is set to “[All]” - otherwise they will not be selected in translations.

Generally these content element types should use the “[All]” language:

• “Insert Plugins”

• “Insert Records” (and make relations to default language records!)

• “Flexible Content Elements” (internally localized in FlexForm)

3.7. TemplaVoilà: Best-practice 55


The “[All]” langauge is set in the “languageField” of the record, for Content Elements:

This will be clearly reflected in the Page module of TemplaVoilà:

3.8 TemplaVoilà: Translator workflow

When you are limited users to languages you effectively define translator roles. This can have a few pleas-ant effects in terms of simplified interfaces in TYPO3. One is the use of display conditions in FlexForms,“HIDE_L10N_SIBLINGS” (see elsewhere).

Another is that TemplaVoilà’s Page module will scale down its buttons when a user does not have access to thedefault language (thus assumed to be a translator). It works out of the box:

3.8.1 ((generated))

Translators (with access to only alternative languages):

Notice how all buttons has been stripped away. There are not even context menu links on item icons and no textsare clickable. Translators simply doesn’t need any of this; all they need is links to translate the content.

Users with access to default language:

This is the normal view of the Page module for TemplaVoilà. Here you see all the additional buttons.



The concept of the scaled down view for translators is to provide a very simply rule for them: “Click the flag!”. Allflags either leads to localization of a record or to editing of an existing translation. No confusion possible.

Another feature is that the view page icon will send the &L parameter according to language selected:

Having Danish selected will automatically add “&L=xx” to the preview URL:

3.8. TemplaVoilà: Translator workflow 57

CHAPTER

FOUR

CORE SUPPORT FOR LOCALIZATION

4.1 TCA, TCEmain, TCEforms

The support for localization in the core of TYPO3 is based around a scheme where a record in the default language(0) can have other records pointing to it, offering a translation of its content. This sets up some requirements to thetable of such records:

1. A field holding the reference to the system language (sys_language table) must be defined.

2. A field holding the reference to the default language record must be defined

Both these fields are defined in TCAs [ctrl] section for a table.

4.1.1 [languageField]

The first field (referring to the language of the record) is defined by [languageField]. The value of this field is alsoused to control access to localized content (see later)

The [columns] configuration of this field can look like this:

'sys_language_uid' => Array ('exclude' => 1,'label' => 'LLL:EXT:lang/locallang_general.php:LGL.language','config' => Array (

'type' => 'select','foreign_table' => 'sys_language','foreign_table_where' => 'ORDER BY sys_language.title','items' => Array(

Array('LLL:EXT:lang/locallang_general.php:LGL.allLanguages',-1),Array('LLL:EXT:lang/locallang_general.php:LGL.default_value',0)

))

),

Notice how it includes two static items for “Default” and “[All]” languages.

4.1.2 [transOrigPointerField]

The second field (referring to the default language record) is defined by [transOrigPointerField].

The configuration of this field could look like this:

'l18n_parent' => Array ('displayCond' => 'FIELD:sys_language_uid:>:0','exclude' => 1,'label' => 'LLL:EXT:lang/locallang_general.php:LGL.l18n_parent','config' => Array (

59


'type' => 'select','items' => Array (

Array('', 0),),'foreign_table' => 'tt_content','foreign_table_where' => 'AND tt_content.pid=###CURRENT_PID### AND tt_content.sys_language_uid IN (-1,0)',

)),

The example is from the “tt_content” table and the “foreign_table” settings should be adjusted accordingly whenusing other tables of course!

Notice how there is a display condition set on the field which will look what the value of the sys_language_uidfield is and only when that is larger than zero (a language is defined for the record) will this field be shown.

Another interesting point is that it will only look for a default language record in the current pid. This means thata default language record an all its translations must be on the same page! Thisprinciple is also respected bythe API function t3lib_page::getRecordOverlay() which fetches translations of records for the frontend display(when “config.sys_language_overlay = 1 / hideNonTranslated”)!

When the “transOrigPointerField” and “languageField” are defined for a table you will have a nice view of thedefault content shown along with the translation in the TCEforms:

4.1.3 Optional fields

There are some optional fields to include when using the localization support. One is [transOrigDiffSourceField].This can point to a blob field in the record which will store the content of the default langauge record as it waswhen the translation was made. This is then used to display any changes that has occured in the default record sincetranslation happened. In the “Content Elements” (tt_content table) it looks like this:

This allows a translator to easily spot what has changed and he can adjust his translation accordingly.

4.1.4 TCEmain commands for localization

Localizing a record can be done by the command “localize” sent in the cmd-array to TCEmain. This is documentedin “TYPO3 Core API”. This is the command sent when you press the localize button in Web>List or Web>Page foran element.

When this command is issued what happens is that 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 modes.

The “[All]” mode is meant for elements which represent universal content that does not need localization (like theinsertion of a plugin or other records). However they can optionally be translated if a special case is needed.

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


Chapter 4. Core support for localization

4.1.5 Localization command options per field

When a localization command is executed from TCEmain the configuration of each field can contain specialinstructions. For instance; You can have a label prefixed a field (like you see “[Translate to Danish:]” in somescreenshots) or you can have the copying of fields disabled all together (like an image field where you wish toinherit the default value by default).

This is done by the [columns][l10n_mode] setting, documented in “TYPO3 Core API”.

“l10n_mode” does not apply to FlexForm fields. Conceptually, it does not make sense.

4.2 Permissions

For all backend users and groups you can define which backend languages they can edit (exclusively). Thepermissions are enforced over all tables with the [languageField] set.

Settings from groups and subgroups are all added together.

If a user has no “Limit to languages” checkboxes set at all he can edit all languages .

Regardless of “Limit to languages” all users can edit records with “[All]” language.

Setting “Limit to languages” is not only good to protect translators from editing other languages or default content- it is also helpful to limit the confusion a user might have when faced with a Web>List display that includeslocalizations from 10 other languages!

Make sure you use the Tools > User Admin module to check you users permissions for language editing:

4.2. Permissions 61

CHAPTER

FIVE

EXTENSIONS

There are a few extensions which I would like to mention in relation to localization.

5.1 realurl

Realurl produces URLs which are human-readable. Eg. “mysite.com/products/” or “mysite.com/dk/products/”.

If you wish realurl to encode the &L-variable nicely into the URL, here is a configuration which will work for you:

1: $TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(2: '_DEFAULT' => array(3: 'preVars' => array(4: array(5: 'GETvar' => 'L',6: 'valueMap' => array(7: 'danish' => 1,8: 'dk' => 1,9: 'ru' => 2,

10: ),11: 'noMatch' => 'bypass'12: )13: ),14: 'pagePath' => array(15: 'type' => 'user',16: 'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main',17: 'spaceCharacter' => '-',18: 'expireDays' => 3,19: ),20: )21: );

The important part is the lines 4-12 where the GET variable “L” is mapped to string values. As you can see a stringvalue of “dk” or “ru” will be translated to a value for L-var which is respectively 1 and 2. Also, you can see that analternative value for “dk” can be used, namely “danish”.

The “noMatch” setting defines that if neither “dk”, “ru” or “danish” is found as the first segment of the URL path,then the path is forwarded to decoding for the page id and other variables.

An interesting effect is that if you create a page which is called “Danish” in the page tree you will never be able toaccess it in the default language! The reason is that if you access the page “/danish/” then “danish” is mapped to“&L=1” and nothing is left for page decoding!

This table shows the mapping of “L” with realurl

Without realurl

Without realurl:

With realurl

63


With realurl:

Without realurl

index.php?id=22&L=0

With realurl

products/

Without realurl

index.php?id=22&L=1

With realurl

dk/products/

Without realurl

index.php?id=22&L=2

With realurl

ru/products/

Notice, that when a new language is added to the website you will have to update the real-url configuration!

5.2 l10ncm

This extension will add a context menu entry that allows you to localize elements and switch language of the defaultelements:

5.3 rlmp_language_detection

This extension can be included in your template and redirect users to the website in the preferred language indicatedby their webbrowser.

Do not forget to configure default language code in the extension’s TS.


CHAPTER

SIX

TODO LIST FOR LOCALIZATION FEATURES

TYPO3 has an almost complete set of features for localization. Yet, especially features to improve overview andworkflow plus import/export features (to support such as TRADOS) remain.

63

65

frontend localization guide - svti of ‘‘forcecharset’’ the reason is that without a value...

Documents