J2.5

Difference between revisions of "Language Switcher Tutorial"

From Joomla! Documentation

(26 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Joomla 1.6 includes 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 extensions as Joomfish).
+
{{version|1.6,1.7,2.5,3.0}}{{page|needs review}}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 [http://extensions.joomla.org/extensions/languages/multi-lingual-content 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).
  
This is why using the Language Switcher Module to change language is set to redirect to another Content Language Home Page. To be able to implement the feature, 7 aspects have to be dealt with.   
+
'''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   
 
# The Content Language parameters in the Language Manager   
# Assigning these Content languages to various items using the "Language" parameter.   
+
# Assigning these Content languages to various items using the "Language" parameter.  
# Defining a Default Home page Menu item per language   
+
# 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 languagefilter System Plugin   
 
# The mod_languages Module (also called Langswitcher)
 
# The mod_languages Module (also called Langswitcher)
Line 16: Line 41:
 
* 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.   
 
* 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.   
 
* 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.
+
* 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 frontend. 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.  
+
* 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.
 
* 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 in 1.6===
 
===The "Language" parameter in 1.6===
Not only Articles but everything is taggable to a specific Content language.  Modules obviously but also Categories, Banners, Weblinks, Newsfeeds, Menu Items...  
+
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===
 
===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 has to be defined for each 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 default Menu containing a Home page menu item tagged to "All" should still exist, and the menu module displaying it should not be published.
+
'''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===   
 
===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.  
+
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)===   
 
===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.
+
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 published.  When switching languages, the module redirects to the Home page defined for the chosen language. Thereafter, the navigation will be the one defined for that language.  If the plugin 'System - Language Filter' is unpublished, this may have unwanted results.  Method:   
+
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.   
 
* 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.   
 
* 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.  
 
* 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 param it to use flags or text to display the choice in front-end.
+
* 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.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.'''
 
'''* Make sure both the module and the plugin are published.'''
  
 
===Define a default site template per Content language===
 
===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.
 
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===
 
===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.
 
Last but not least, each content language to be displayed should have the Joomla site language pack installed and enabled.
 
===How to Test (in beta 1.6)=== 
 
Obviously, Sample data is not the best way to demonstrate easily the power of this new Feature.  But one can test a simple site with the following actions using the temporary test language xx-XX.  One prerequisite is that it should remain a Home menu item tagged to "All" and defined as default Home, the module displaying it being unpublished or assigned to a non available position in the template 
 
# Define CONTENT LANGUAGES in the Language Manager, URL Language code for the url and flag for each.  Default available are en-GB and xx-XX.
 
# Create a Parent Article Category tagged to en-GB and one tagged to xx-XX 
 
# Create articles in each of these categories, tagging the articles to the same language as the category. 
 
# If you like, create sub categories with articles, all tagged as should. 
 
# Create one menu per language, tagged as should. This will create 2 menu modules. Tag them to the language concerned. 
 
# Create menu items tagged to that language in each menu. For now variations of the Article menu items (blog, list, single...) 
 
# Define one menu item per language/menu as the Home for this language. 
 
# Publish the langswitcher module (tagged to language "All") and assign ONLY to each Content Language Home Menu Item (Parks Home and Fruitshop Welcome in the fast test) 
 
# Publish the languagefilter plugin.
 
  
  
'''Tip for a fast test:''' [Tag the Park Home menu item to en-GB and as Default Home, same for the Fruitshop Welcome menu item tagged to xx-XX and set as default home for this language. Make sure the langfilter plugin is published and that the langswitcher module is published and assigned to position7 for the 2 home pages]
 
  
 
[[Category:Joomla!  1.6]] [[Category:Tutorials]]
 
[[Category:Joomla!  1.6]] [[Category:Tutorials]]
 +
<noinclude>[[Category:Joomla! 1.6]] [[Category:Languages]]</noinclude>

Revision as of 06:08, 21 March 2013

The "J2.5" namespace is a namespace scheduled to be archived. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Copyedit.png
This Page Needs Your Help

This page 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.

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

The "Content" tab in Language Manager[edit]

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 in 1.6[edit]

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[edit]

  • 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[edit]

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[edit]

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)[edit]

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[edit]

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[edit]

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