Language Switcher Tutorial

This page contains changes which are not marked for translation.

Languages:

English

This article is for Joomla! CMS Version(s)

This Article Needs Your Help

This article is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.

The Joomla 2.5 series include a basic way to implement a multi-language site. This feature does not work as an association-type display where each content, whatever it is, has an equivalent in another language (it does not replace other multi-lingual extensions managers, such as Joomfish). This is why using the Language Switcher Module to change language is set to redirect to another Content Language Home Page (1.6).

Here is a pdf tutorial http://help.joomla.org/files/EN-GB_multilang_tutorial.pdf

NEW! We do now have an official multi-lingual demo site with tutorial and back-end access. It is updated to 2.5.x presents a tutorial in 6 languages

See: http://multilingual-joomla-demo.cloudaccess.net/

NEW in Joomla 1.7: Menu items may be associated in different languages. When a menu item, let's say tagged to fr-FR, is associated to a menu item tagged en-GB, if the language switcher module is present on the page, clicking on the en-GB flag/name redirects to the en-GB menu item and reciprocally. If a menu item is not associated, the behavior will be the same as in 1.6, that is redirect to the home page in the language concerned. This let's therefore the choice for the webmaster to associate or not, item per item.

See: http://community.joomla.org/blogs/community/1468-multilang-in-17-whats-new.html

NEW in Joomla 1.7.1: is now included a multilanguage status administrator module.

See: http://community.joomla.org/blogs/community/1501-171-new-multilanguage-status-module.html

NEW in joomla 1.7.3 Among other improvements, now available is the possibility of not displaying the language prefix for the site default language.

See http://community.joomla.org/blogs/community/1522-languages-173-improvements.html

Also, an official demo site is now available with access to administrator: http://multilingual-joomla-demo.cloudaccess.net/

To be able to implement the feature, 8 aspects have to be dealt with.

The Content Language parameters in the Language Manager
Assigning these Content languages to various items using the "Language" parameter.
Create a correct site structure • Important !!!
Defining a Default Home page Menu item per language and keep one separate tagged to "All" languages.
The languagefilter System Plugin
The mod_languages Module (also called Langswitcher)
Define a default site template per Content language if needed.
Make sure the site language packs are installed and enabled for any content language you want to display

1 The "Content" tab in Language Manager
2 The "Language" parameter
3 The structure of the site, simple rules
4 Defining a Default Home page Menu item per language
5 The languagefilter System Plugin
6 The mod_languages Module (also called Langswitcher)
7 Define a default site template per Content language
8 Install the necessary site language packs

The "Content" tab in Language Manager

There, one can create a "Content Language", even if the site language is not yet installed.

Title = The name of the language as it will appear in the dropdown lists when assigning the language to an item. This Title will also be used by the langswitcher module in front-end when flags are not used.
Title Native = A title in any language desired by the admin to be displayed in the Content Language list.
URL Language Code= This Language Code will be appended to the site url. When SEF is enabled, one will get http://mysite.com/en/. If SEF is disabled the suffix &lang=en will be appended at the end of the URL. Note the Language Code must be unique among all the languages.
Image Prefix = Prefix of the image file for this language when using the "Use image flags" Language Switcher basic option. Example: if 'en' is chosen, then the image shall be en.gif. Images and CSS for this module are in media/mod_languages/ . Users can add any image/flag there with any prefix. Example: pt_br for the Brazilian flag.
Language Tag = Enter here the language tag example: en-GB for English (UK). This should be the exact prefix used for the language installed or to be installed.
Published = Whether this content language is published or not. If published, it will display as a choice in the Language Switcher module in front end. To work OK, the specific site language must be installed. One can prepare contents in a specific Content Language without even installing the language concerned, and just do it when deciding to publish that language.
Metadata = These metadata definitions will override Global Configuration Metadata in Multilanguage configuration for each language used.

Make sure your ready-to-go Content languages are published if you want them to display in the langswitcher module. Also make sure your language tag is correct ( en-GB and not en_GB ), this causes the language selector to be empty. If you have completed all steps and the language selector remains empty, check that i.e. the folder language/nl-NL exists and it should contain several .ini files.

The "Language" parameter

Not only Articles but everything is taggable to a specific Content language. Modules obviously but also Categories, Banners, Weblinks, Newsfeeds, Menu Items...

The structure of the site, simple rules

Create root categories for each language. Sub-categories and contents SHOULD be tagged to the same language. Internal links in these contents should only link to contents tagged in the same language.

ROOT (Internal Joomla core structure)

Category root ALL

Contents ALL

Subcategory ALL

Contents ALL

etc.

Category root Lang1

Contents Lang1

Subcategory Lang1

Contents Lang1

etc.

Category root Lang2

Contents Lang2

Subcategory Lang2

Contents Lang2

etc.

Create menus for each language. The menu items in these menus should be tagged to a unique language and display ONLY items tagged to the same language (or "All"). The modules displaying these menus should also be tagged to the same language.
"All" is considered as a language and should follow the same rules (Root categories tagged to "All", internal links to contents tagged to "All", Menus specifically containing menu items tagged to "All" and displaying tagged to "All" contents, modules tagged to "All"). Items tagged to "All" will display on front-end for all languages.

Defining a Default Home page Menu item per language

As the Language Switcher Module is set to redirect to another Content Language Home Page, one Default Home page menu item has to be defined for each language in a different menu, displayed by a different menu module.

Important Note: A Menu containing a unique Default Home page menu item tagged to "All" should still exist, and the menu module displaying it should not be published or assigned to a position NOT available in the templates.

WARNING! Some templates available on the Net are not totally 1.6 compatible. They do not let create new styles and force to use a unique Default Home page.

The languagefilter System Plugin

This plugin filters the displayed content depending on language. This plugin is to be enabled -only- when the Language Switcher module is published. Parameters are to be set for the plugin.

Peculiarly the Menu Association parameter.

The mod_languages Module (also called Langswitcher)

This module displays a list of available Content Languages (as defined and published in Language Manager Content tab) for switching between them when one wants to use Joomla! as a multilanguage site. Parameters are to be set for the Switcher.

The plugin 'System - Language Filter' has to be enabled. When switching languages, the module redirects to the Home page defined for the chosen language.

NEW in 1.7, when menu items are associated, the module should be displayed on the pages concerned. In this case the redirection will be done to the associated menu items.

Thereafter, the navigation will be the one defined for that language. If the plugin 'System - Language Filter' is disabled, this may have unwanted results. Method:

Open Language Manager Content tab and make sure the Languages you want to use in contents are published and have a prefix for the URL as well as prefix for the image used in the module display.
Create a Home page by assigning a language to a menu item and defining it as Default Home page for each published content language.
Thereafter, you can assign a language to any Article, Category, Module, Newsfeed, Weblinks in Joomla.
Assign the Langswitcher module to each Specific Default Language Content Home page and associated menu items pages and param it to use flags or text to display the choice in front-end.
New parameters for 1.6.1: display or not the active language, choose between horizontal and vertical display.
New parameters for 1.7.0: choice for dropdown and shortcut for language names.

* Make sure both the module and the plugin are published.

Define a default site template per Content language

If one wants to use different templates styles per Content language, instead of defining for each menu item a different template style, one can assign globally a template style per language when editing it in the Template Manager. This is very handy when one needs to use different headers, logos, etc. for each Content language. It also covers any issue arising from loading a page not linked to any menu item where the default template style would be used, whatever it is.

Warning: some templates available on the Net do not let you choose a different menu containing its language tagged Default Home page for each template style. This will break 1.6/1.7 multilang.

Install the necessary site language packs

Last but not least, each content language to be displayed should have the Joomla site language pack installed and enabled.