DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Language Selection

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed by:Stanislas Rolland
Changed:2018-10-15T12:02:34.170000000
Email:typo3(arobas)sjbr.ca
Info 2:Stanislas Rolland
Info 3:
Info 4:

EXT: Language Selection

((generated))

Table of Contents

Copyright 2

Credits 2

Sponsors 2

Introduction 3

What does it do? 3

Requirements 3

Users manual 4

Adding a Language Selection widget in a Fluid template 4

Adding a Language Selection menu using TypoScript 4

Creating a Language Selection content element 4

Configuration 6

Configuration steps 6

Typoscript Constants Reference 6

TypoScript Setup Reference 8

Fluid template variables 9

Upgrading to version 6.0 10

Change Log 11

Introduction

What does it do?

The Language Selection extension provides a Fluid widget that allows to insert a language selection menu in a Fluid template.

The extension also provides a new type of TYPO3 content element . This content element may also be used to insert a language selection menu on a page.

The language selection menu has the following features:

  • the menu may be presented as a list of flags, as a selector box, or as a list of links;
  • clicking on a flag, selecting a language in the selector box, or clicking on the language name in the list of links loads the corresponding version of the page;
  • if the list is presented as a list of flags, a flag is dimmed when the current page does not have a version in the corresponding language; if the list is presented as a selector box, only the languages for which the current page has a version are presented in the list;
  • optionally, no menu is presented if the current page has no alternate language;
  • the name of each language may be presented in the language itself;
  • a collection of flags for the languages supported by Typo3 is included with the extension; the flags are derived form the collection flags-1.6.tgz available at the Open Clip Art Library ;
  • the extension is DBAL-compatible and the output is HTML5 compliant and CSS-styled;
  • the extension is built with Extbase and Fluid.

Requirements

Version 6.5.0 of this extension requires TYPO3 CMS 9.5+ and extension Static Info Tables 6.7.0+ (key: static_info_tables).

Version 6.4.3 of this extension requires TYPO3 CMS 7.6+ and extension Static Info Tables 6.4.2+ (key: static_info_tables).

Version 6.4.0 of this extension requires TYPO3 CMS 7.6+ and extension Static Info Tables 6.3.1+ (key: static_info_tables).

Version 6.3.3 is the last version of this extension that will work with TYPO3 CMS 6.2 LTS.

Version 6.0.7 is the last version of this extension that will work with TYPO3 CMS 6.0-6.1.

Version 1.5.2 is the last version of this extension that will work with TYPO3 CMS 4.0-4.7 and version 2.0.0 of extension Static Info Tables (key: static_info_tables).

Users manual

First, the extension needs to be installed and configured: see the Configuration section.

Second, each of the Website language records should be assigned an ISO language code in the field titled “Select Official Language (ISO code)”.

Then, you are ready to insert Language Selection content elements on your pages.

Adding a Language Selection widget in a Fluid template

At the top of your Fluid template, namespace the extension view helpers:

{namespace languageMenu=SJBR\SrLanguageMenu\ViewHelpers}

Then, insert the widget wherever it is needed, for example:

<languageMenu:widget.menu languages="0,2,3" layout="Flags" languageTitle="1" />

The widget accepts three arguments:

  • languages: the ordered list of uid’s of Website language records you want to see in the menu;
  • layout: a keyword for the layout you want the menu to be rendered with: Flags (a list of flags), Select (a selector box), Links (a list of links);
  • languageTitle: the labels you want to use for the languages: 0 (the name of the language localized in the language of the current page), 1 (the name of the language in the language itself), 2 (the name of the language as set in the Website language record in the TYPO3 backend), 3 (the ISO language and, possibly, country codes of the language).

Any argument that is not present will get the value specified in the TypoScript template setup.

Adding a Language Selection menu using TypoScript

If you want to use TypoScript to include the Language Selection element on a PAGE or other type of TypoScript object, simply assign plugin.tx_srlanguagemenu.widgets.menu to the object. For example:

subparts.languageMenu < plugin.tx_srlanguagemenu.widgets.menu

This will create a language menu using the current TypoScript setup for all settings of the menu.

Creating a Language Selection content element

You create a Language Selection content element the same way as any other type of content element. When the default content element creation form is displayed, select the type Language Selection; the form is redisplayed. Or use the new content element creation wizard to get a Language Selection creation form directly.

The Language Selection creation form includes a Menu settings tab. This tab itself includes a General and a Template tab.

In the General tab:

The field “Type of layout” allows to choose the type of layout or presentation:

  • a list of flags,
  • a drop down selection list,
  • or a list of links.

The field “Languages to select from” allows you to select languages from the Web Site Language table. Note that the default language of your site may not appear in this list. If the list is empty, the list provided by the TS template will be used. If the list is not empty, it also specifies the order in which the languages will appear in the menu.

The field “Position of the default language” allows to specify the position at which the default language will be inserted in the menu.

The field “Language title to use” lets you select the labels you want to use for the languages:

  • the name of the language localized in the language of the current page,
  • the name of the language in the language itself,
  • the name of the language as set in the web site language record in the TYPO3 backend,
  • the ISO language and, possibly, country codes of the language.

In the Template tab, you may override the paths to the Fluid template root, as well as to the partials and layouts.

Configuration

Configuration steps

These are the steps to configure the Language Selection plugin:

Install the extension using the Extension Manager and run the update script. Note that when upgrading to version 6.0+, the update script will do irreversible updates to the database .

Include static template “Language Menu Setup” in your TypoScript template, and configure the plugin using the TypoScript Constants Editor. Review the plugin settings described below.

Include default CSS styles by including static template “Language Menu CSS Styles” in your TypoScript template, or adapt these default selectors according to the visual design of your site and include them in the style sheets of your site.

Adapt the Fluid templates to your needs. You may copy them to a location of your choice, adapt them, and configure the new location using the TypoScript Constants Editor.

Typoscript Constants Reference

file.templateFile

Property

file.templateFile

(REMOVED)

Data type

fileResource

Description

The name of the HTML template file.

Note: the extension now uses Fluid templates rather than HTML templates.

Default

defaultLanguageISOCode

Property

defaultLanguageISOCode

Data type

string

Description

Language ISO-alpha-2 code of default site language.

This is the language ISO-alpha-2 code of the site language when sys_language_uid = 0

Default

EN

defaultCountryISOCode

Property

defaultCountryISOCode

Data type

string

Description

Country ISO-alpha-2 code of default site language.

This is the country ISO-alpha-2 code of the site language when sys_language_uid = 0

Default

defaultLanguageTitle

Property

defaultLanguageTitle

Data type

string

Description

Title of the default site language

This is the language label when sys_language_uid = 0 and web site language records are used for language labels. If not set, the localized name of the language from Static Info Tables is used based on the default langugae ISO code and the default country ISO code.

Default

englishFlagFile

Property

englishFlagFile

Data type

fileResource

Description

Name of the file of the English language flag.

All flags should be in the same directory as this one.

Default

EXT:sr_language_menu/Resources/Images/Flags/en.png

languageTitle

Property

languageTitle

Data type

integer

Description

The labels to use for the languages.

Possible values:

0 - the name of the language localized in the language of the current page

1 - the name of the language in the language itself

2 - the name of the language as set in the web site language record in the TYPO3 backend

3 - the ISO language and, possibly, country codes of the language

Note: This will take precedence over deprecated properties useSysLanguageTitle, useIsoLanguageCountryCode and useSelfLanguageTitle.

Default

0

useSysLanguageTitle

Property

useSysLanguageTitle

(DEPRECATED: use languageTitle)

Data type

boolean

Description

Use the sys_language title.

If enabled (set to 1), the title field of table sys_language will be used instead of the language name from the static_languages table.

Default

0

useIsoLanguageCountryCode

Property

useIsoLanguageCountryCode

(DEPRECATED: use languageTitle)

Data type

boolean

Description

Use the ISO language and country codes.

If enabled, the ISO language code and, possibly, the country code will be used instead of the language name from the static_languages table.

Note: Ignored if useSysLanguageTitle is enabled.

Default

0

useSelfLanguageTitle

Property

useSelfLanguageTitle

(DEPRECATED: use languageTitle)

Data type

boolean

Description

Display name of language in the language itself.

If enabled, the name of the language will be displayed in the language itself.

Note: Ignored if either useSysLanguageTitle or useIsoLanguageCountryCode is enabled.

Default

1

languagesUidsList

Property

languagesUidsList

Data type

string

Description

List of uids of language records from table sys_language.

Note: This list will be used by default to build the list of languages to select from, if no list is otherwise provided to the plugin.

Note: If the list is empty and not otherwise provided to the plugin, all languages found in table sys_language will be used.

Note: If the list is not empty and not otherwise provided to the plugin, it also specifies the order in which the languages appear in the menu.

Default

defaultLayout

Property

defaultLayout

Data type

string

Description

Default layout.

Possible values: 0 = flags, 1 = selection list, 2 = list of links.

Note: This is the layout to be used, if no layout is otherwise provided to the plugin.

Default

0

showLinkWithFlag

Property

showLinkWithFlag

Data type

boolean

Description

Show both links and flags.

If enabled, when using the flags layout, both flags and links may be shown.

Default

0

hideIfNoAltLanguages

Property

hideIfNoAltLanguages

Data type

boolean

Description

Hide selection if there is no alternate language

If enabled, the selection list or menu is not rendered if no alternate languages are present on the current page.

Default

0

showCurrent

Property

showCurrent

Data type

boolean

Description

Show the language of the current page in the language menu.

If enabled, the current language is shown in the language menu.

Note: Beware that this constant is used in the default setup. Setting a property with the same name in TS setup will not work.

Default

1

showCurrentFirst

Property

showCurrentFirst

Data type

boolean

Description

Show the language of the current page first in the language menu.

If enabled, the current language is always the first item shown in the language menu.

Default

0

showInactive

Property

showInactive

Data type

boolean

Description

Show in the language menu the languages for which there is no translation of the current page.

Note: This property does not apply to the selection list layout.

Note: Beware that this constant is used in the default setup. Setting a property with the same name in TS setup will not work.

Default

1

doNotLinkCurrent

Property

doNotLinkCurrent

Data type

boolean

Description

Do not wrap the current language in a link.

Note: This property does not apply to the selection list layout.

Default

0

doNotLinkInactive

Property

doNotLinkInactive

Data type

boolean

Description

Do not wrap inactive language in a link.

Note: This property does not apply to the selection list layout.

Default

1

pointerImage

Property

pointerImage

(REMOVED)

Data type

string

Description

File name of the pointer image.

Note: The pointer image is renderedd through CSS styles. See EXT:sr_language_menu/Resources/Public/StyleSheets/SrLanguageMenu.css

Default

Separator

Property

Separator

(REMOVED)

Data type

string

Description

Separator between links.

Note: The separator is renderedd through CSS styles. See EXT:sr_language_menu/Resources/Public/StyleSheets/SrLanguageMenu.css

Default

Token

Property

Token

(REMOVED)

Data type

string

Description

Token used in stdWrap split of the list of flags and the list of links.

Note: stdWrap split of the list of flags and the list of links was removed. This is now performed in the Fluid templates.

Default

removeParams

Property

removeParams

Data type

string

Description

List of parameters that should not be forwarded when linking to another language.

Note: The list may include the name of an array of variables such as the array of variables of a plugin, for example “tx_myplugin”.

Default

user.pass

allowedParams

Property

allowedParams

Data type

string

Description

List of parameters that are allowed to be forwarded when linking to another language

Note: If specified, only parameters in this list or in config.linkVars may be forwarded when linking to another language.

Note: The list may include the name of an array of variables such as the array of variables of a plugin, for example “tx_myplugin”.

Note: This property provides a way to prevent pollution of linkvars, and resulting spammed cache.

Default

addSelectionListHeader

Property

addSelectionListHeader

Data type

boolean

Description

If enabled, when the layout is a selection list, a header will be added at the top of the list.

Default

0

selectionListSeparator

Property

selectionListSeparator

Data type

string

Description

Separator between the selection list and its header, if the selection list header is enabled.

Default

onChangeAttribute

Property

onChangeAttribute

Data type

boolean

Description

If enabled, a submit on change attribute is set on the selection list; thus the selected language is submitted as soon as it is selected.

If disabled, a button must be clicked on to submit the selection.

Note: When disabled, no javascript is used by the language selection form.

Default

1

addLinksListHeader

Property

addLinksListHeader

Data type

boolean

Description

Add a header in front of the list of links.

If enabled, when the layout is a list of links, a header will be added at the top of the list.

Default

0

TypoScript Setup Reference

flag.CUR.stdWrap

Property

flag.CUR.stdWrap

(REMOVED)

Data type

stdWrap

Description

stdWrap to be applied to the active language or, in other words, to the currently displayed language in the list of flags.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flag.CUR.doNotLinkIt

Property

flag.CUR.doNotLinkIt

(REMOVED)

Data type

boolean

Description

If set, no link is wrapped around the flag of the current language.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flag.NO.stdWrap

Property

flag.NO.stdWrap

(REMOVED)

Data type

stdWrap

Description

stdWrap to be applied to normal, not currently displayed language in the list of flags.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flag.INACT.stdWrap

Property

flag.INACT.stdWrap

(REMOVED)

Data type

stdWrap

Description

stdWrap to be applied to inactive languages in the list of flags or, in other words, to languages that are not available for the currently displayed page.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flag.INACT.doNotLinkIt

Property

flag.INACT.doNotLinkIt

(REMOVED)

Data type

boolean

Description

If set, no link is wrapped around the flags of the inactive languages.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flags.stdWrap

Property

flags.stdWrap

(REMOVED)

Data type

stdWrap

Description

stdWrap to be applied to the list of flags.

Note: stdWrap of the list of flags was removed. This is now performed in the Fluid templates.

Default

flag.INACT.stdWrap

Property

flag.INACT.stdWrap

(REMOVED)

Data type

stdWrap

Description

stdWrap to be applied to inactive languages in the list of links or, in other words, to languages that are not available for the currently displayed page.

Note: stdWrap of the list of links was removed. This is now performed in the Fluid templates.

Default

useExternalUrl. [language-iso-code]

Property

useExternalUrl. [language-iso-code]

Data type

url

Description

If no alternate language record exists on a page for the language identified by the language-iso-code, a link will be created to the specified external url for this language.

Default

useExternalUrl. [language-iso-code] .force

Property

useExternalUrl. [language-iso-code] .force

Data type

boolean

Description

If set, a link will be created to the specified external url for this language, even if an alternate language record exists on a page for this language.

Default

0

forceUseOfExternalUrl

Property

forceUseOfExternalUrl

Data type

boolean

Description

If set, then, if an external url is specified for a any language, a link will be created to the specified external url, even if an alternate language record exists on a page for this language.

Default

0

Fluid template variables

The following objects are available in the Fluid template:

  • settings: an object providing all the properties of the plugin settings, plus the additional property showMenu: whether or not the menu should be rendered;
  • options: an array, each element of which is an option of the menu.

Each option has the following properties:

  • uid: the uid of the Website language;
  • isoCodeA2: the ISO code of the language;
  • countryIsoCodeA2: the ISO country code of the language variant;
  • combinedIsoCode: the combination of isoCodeA2, lower case, and of countryIsoCodeA2, if present, uppercase, joined by an undescore;
  • title: the language label;
  • notAvailableTitle: label used when the page is not available in the language;
  • flagFile: the path to the flag file;
  • isAvailable: whether or not a translation of the current page is available in the language;
  • externalUrl: external url to be used in place of the current page id;
  • isCurrent: whether or not the page is currently rendered in the language.

Example: Apply TypoScript stdWrap to the language label

Add the following snippet to your TypoScript template setup:

lib.myLanguageLabel = TEXT
lib.myLanguageLabel {
    current = 1
    stdWrap.substring = 0,3
}

Then, in the Fluid templates, replace any occurrence of

{option.title}

by

{option.title -> f:cObject(typoscriptObjectPath: 'lib.myLanguageLabel')}

Or use an alias:

<f:alias map="{label: '{option.title -> f:cObject(typoscriptObjectPath: \'lib.myLanguageLabel\')}'}">

The desired shortened label is rendered.

Upgrading to version 6.0

Install the new version. You may need to upgrade extension Static Info Tables.

Run the update script. Beware that the script will make IRREVERSIBLE updates to the database.

The update script will update all occurrences of the plugin in table tt_content changing the plugin CType from “tx_srlanguagemenu_pi1” to “srlanguagemenu_languagemenu” and adding the data of a flexform based on the values of the fields previously added by the “tx_srlanguagemenu_pi1” plugin.

The update script will also update the constants and setup fields of all TypoScript templates replacing, in the constants fields, all occurrences of “tx_srlanguagemenu_pi1” with “tx_srlanguagemenu”, and, in the setup fields, all occurrences of “tx_srlanguagemenu_pi1” with “tx_srlanguagemenu.settings”. After this update, you may need to move array _LOCAL_LANG from plugin.tx_srlanguagemenu.settings to plugin.tx_srlanguagemenu.

Static template “Language Menu Setup” must now be included on the TypoScript template of any page containing the plugin. If you want the default CSS of the plugin to be included on these pages, you must also include static template “Language Menu CSS Styles”.

Some TypoScript constants and setup properties were removed and others where deprecated. Review your plugin configurations against the “TypoScript Constants Reference” and the “TypoScript Setup Reference”.

The plugin does not use an HTML template anymore. If you had modified the HTML template, you may need to adapt the Fluid templates provided by the extension.

You may also need to adapt your style sheets as the plugin CSS selectors were modified. In particular the main selector was changed from tx-srlanguagemenu-pi1 to tx-srlanguagemenu.