MATsxm/Setup a Multilingual Joomla Site-Adding a language
From Joomla! Documentation
Text to translate
This user page or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this user page or section has not been edited in several days, please remove this template.
How to setup a Multilingual Joomla! Site
Joomla! allows you to to create relatively easy a multilingual website, without having to install any third party extension. In this tutorial, you’ll find a complete walkthrough of the steps involved in creating a multilingual Joomla! site.
Installing a new language
Option 1: Setup a Multilingual site on an existing site
In this tutorial, the default language of the site is English. For users speaking another language, there should be a language switch available giving them access to the same content but in a different language. Here, we’ll use French as the second site language - but that’s just for demonstration purposes. You can follow along with the steps below using any language you need.
Although creating a multilingual website isn’t complicated, it involves following a number of essential steps. Therefore, we’ll start with a fresh install of Joomla! 3.x, without sample data. This way, we can keep things simple and get a good idea of the full process. After you’ve mastered the basic principles, it’s easier to apply them to an existing site that already contains content in one language.
Checking which languages are currently available
After installing Joomla, one language is available. You can check this by navigating to Extensions → Language(s). In this example, the currently installed language is British English (en-GB).
In the side menu, Installed - Site indicates the language Joomla! uses in the frontend (texts such as Read more, Articles and Category). By clicking on Installed - Administrator you can see what language is installed for the backend.
Adding a new language
First, let’s add the language files for the language we want to use as the second language on our site. This involves two steps:
- installing the French language package
- telling Joomla! we want to use it as a content language.
Installing a new language package
Let's install the French language package.
- Go to Extensions → Language(s)
- Click the button at the top left Install Language.
A list of available translations is displayed. You can easily find the desired language by using the Search function. In this field, enter French.
Check the box on the left side of French language and click the top left button Install. Then, a message is displayed: Installation of The French(FR) was successful. Mission accomplished! In the Languages screen (accessed through Extensions → Language(s)), you can now see that French (fr-FR) language is now available.
Option 2: Setup a multilingual site during a new installation
Creating a Content Language
The next step is to create a Content Language. Although you’ve already installed a second language pack (in this example the French language pack), you still need to add the appropriate details for this language. To do this, you need to add what Joomla! calls a Content Language. It's a bit like a "language profile", containing all the details needed by Joomla! to be able to use either the English or the French language as "switchable" content languages.
- In the Language Manager screen, click on Content Languages in the left sidebar. At this step, there is just one Content Language available: English.
- Click the button New.
- In the Edit Content Language screen, add the following details for the new language:
- Title: Français (FR). This is the language name as it will appear in the lists.
- Title Native: Français (FR). This the original language name. This title will be displayed in the Language Manager, in the list of Content Languages.
- Language Tag: fr-FR. This should be the exact prefix used for the language installed (or to be installed). It consists of the language code (in lowercase), an hyphen and the country code (in uppercase). If you’re not sure about the Language Tag, you can find it next to the language name in the list of installed site languages in the Language Manager.
- URL Language Code: fr. This is the code Joomla! will append to the site URLs. In our example, the output will be:
www.example.com/fr/if SEF is activated (if SEF is disabled, the output will be
&lang=fr). Each installed language must have a unique code.
- Image Prefix: select fr. Joomla! uses this code to display a country flag image enabling the visitor to select a site language. When fr is selected, Joomla! will display the flag image fr.gif located in the folder media/mod_languages/images/.
- Status: this should be set to Published.
- Access: this should be set to Public.
- Click Save & Close. The Content Language profile is now ready!
Step 3 - Enabling the Language Filter plugin
Joomla! comes with a language filter plugin, which enables the CMS to recognize the different installed languages and display only the content relevant to the current language.
Edit this plugin to change its settings:
- Go to Extensions → Plugins.
- Search and edit the plugin System - Language Filter.
- Switch its Status to Enabled.
- Item associations: Set to Yes. This option will allow item associations when switching from one language to another.
- Remove URL Language Code: To create search engine friendly URLs in the multilingual site, set Remove URL Language Code to Yes.
- Click Save & Close.
The language files are new set up properly and you’ve switched on Joomla’s built-in Language Filter. By default, this plugin will try to detect the language settings of the visitor browser and display the site in this language (if available).
Step 4 - Enabling the Language Code plugin
Joomla! comes with a built-in language code plugin, which provides the ability to change the language code in the generated HTML document to improve SEO. The fields will appear when the plugin is enabled and saved.
- Go to Extensions → Plugins.
- Search the plugin System - Language Code.
- Switch its Status to Enabled.
Step 5 - Adding multilingual content
The next step is to create the actual content that needs to be displayed in different languages. To neatly organize the content that belongs to different languages, you need to create specific categories holding (in this case) English and French content.
Creating language categories
We’ll add two top-level categories: one which will contain our English content, the other one for the French content.
- Go to Content → Categories
- Click New at the top left to create a new category. This new category will become the parent category for all French articles, so let’s call it Français.
- In the Language drop-down list, select Français.
- As it’s a parent category, it should have No parent.
- Click Save & Close.
- Repeat these steps to create a second category for the English Articles called English. Set the Language to English.
- You now have two categories in your site! The Categories screen should now contain a parent category called Français and one called English. You'll may need to organize the site content using subcategories of these two main categories. In this example, we'll not create any subcategory.
Adding content to the new categories
Next, create a set of (dummy) articles. We’ll create a few English articles and their French counterparts. In this example, we’ll create four articles in the English category and four articles in the French category. Navigate to Content → Article. Create a new article called English Article 1. Add some dummy text. Make sure to assign the article to the English category. In the Language drop-down list, select English. Repeat the actions described in the previous step to create a set of articles called English Article 2, English Article 3. You’ve now got three English articles. Instead of creating three corresponding French articles from scratch, let’s copy the English articles. To do this, select all three articles in the Content → Article screen and click the Batch button. In the Batch process the selected articles popup screen, choose the following settings:
- Set Language: French.
- Select Category for Move/Copy: French.
- Click the Copy select box and click Process.
You’ve now got a set of six articles: three articles assigned to the English category and their copies, assigned to the French category. Open the first of the four articles that are assigned to the French category. Change the following details:
- Title: enter the French title. In this case we’re only testing things out, so we won’t bother translating. Let’s enter French Article 1.
- Under Publishing Options, delete the contents of the Alias field. Joomla will instead add a unique alias for this article after you’ve saved the article.
- In the article text, just change a few words to be able to be able to check later if the "French" text is displayed.
- Click Save & Close.
Next, open the other French articles one by one and change the details accordingly. The output should be French Article 2 to French Article 3, all assigned to the French category, assigned to Language: French. The (dummy) content is ready. We’ve got two small groups of articles; each of these articles has been assigned to the appropriate language.
Next, we’ll create a menu for each of the languages. As you would expect, we’ll need a menu pointing to the English articles and a separate menu pointing to the French articles.
Navigate to Menus → Manage → Add New Menu. First create a menu for the French language articles. As the Title, enter French Menu. As the Menu Type, enter frenchmenu. Finally, add a Description (ie Menu for French content). Click Save & Close.
Now create another menu for the English language. As the Title, enter English Menu. As the Menu Type, enter englishmenu and add a Description and save the menu.
You’ve now got two sets of content and two menus, ready to be filled with menu items.
- Adding menu items
The two new menus are still empty, so let's add a set of menu items to them.
Navigate to Menus French Menu → Add New Menu Item. We'll keep it simple and create a menu link of the Single Article type. Make this menu link point to French Article 1. As the menu Title, enter French Article 1. Make sure the Menu Location is French Menu and set the Language to French.
Repeat the actions described in the previous step until you’ve got four menu items in the French Menu, each pointing to one of the three available French articles.
Now navigate to Menus → English Menu and create three menu links pointing to the three English articles. To do this, repeat the actions you took in steps 1 and 2, changing the details as needed.
The outcome should be a set of three menu links in the English menu, as shown in the screenshot below.
- Assigning language-specific home pages to the new menus
Your English and French menus both contain all necessary menu links. However, Joomla needs to know what menu link in either of these menus should be the default link (the default homepage to be displayed for either the English site or the French site). Let’s set one of the menu items to be the default homepage for this language.
Navigate to Menus → Menu Manager and click the name of the English Menu toopen it. Click on the star in the Home column next to the first article.
The star icon changes to an image of the British flag, indicating this is the default page for the English part of the site.
Navigate to Menus → French menu and click the Home star next to the first French article. The star turns into a French flag.
- Connecting menu links to their translated counterparts
Although you have two sets of articles (original articles and their French "translations"), up to now there’s no connection between these articles. Joomla has no way of knowing what French article should serve as the translated alternative of a particular English menu item. Let’s connect (associate) the English menu items with their translations.
In the Menu Manager, open the French Menu and click the first menu item to edit it (in this example, this is the French Article 1 menu link). You’ll notice this menu item has a separate Associations tab. Click this tab and click the English (UK) drop-down list. Select the appropriate English menu link: English Article 1.
Save this menu item.
Repeat the previous steps to create associatons for all four French menu links. Open each menu link, select its appropriate English counterpart and save it. As a result, you should now have four Menu Items that are associated with French Menu Items. In the Menu Manager: Menu Items screen, you can easily check this: in the Association column, an icon (a chain in a blue circle) is displayed. Hover your mouse cursor over the image to see the associated menu items, as shown in the screenshot below.
- Finalizing the new menus by adding menu modules
Both new menus have been created, and menu links have been assigned to them. However, as is the case with every new menu created in Joomla, you’ll also have to add a menu module in order to be able to display the menu on the site. Let’s add these modules for both menus.
1. Navigate to the Menu manager. Locate the French Menu and click the Add a module for this menu type link in the Linked Modules column. In the Module Manager: Module Menu screen, enter the following Title: French Menu. In the Language drop-down list, select French (FR). In the Position drop-down list, select position-7. Click Save & Close to commit changes.
Add a menu module for the English menu by repeating the previous steps, changing the details as necessary: in the Menu Manager, click the Add a module for this menu type link, name the new module English Menu, set the language to English (UK), assign it to position-7 and click Save & Close.
- Unpublishing the default Main Menu
Apart from the two new menus, the website also contains the Main Menu that’s part of the Joomla default setup. If you’ve installed Joomla without sample data, this menu contains only a Home link. Although the bilingual site will use the new English Menu and the new French Menu, Joomla will still need the default main menu and the Home link in it to function. Joomla also requires the Main Menu module to remain assigned (as it is by default) to Language: All. However, the Main Menu doesn’t need to be displayed any more on the site. For this reason, we’ll unpublish the menu module associated with the Main Menu.
1. Navigate to Extensions → Module Manager, locate the Main Menu module and click its Title to edit it.
2. Change the Status to Unpublished. Save your changes.
The menus for the multilingual content are finished. Just one more step to go: adding a language switcher enabling web visitors to select their prefered language.
Step 7 - Adding a Language Switcher
If you were to leave the site as it is, you would have two sets of articles, one French, one English. However, only one menu would be displayed: either the English Menu or the French Menu. Joomla would decide between serving English or French content depending on the language settings of the visitors browser.
However, we want the visitor to be able to actively switch to the translated content in another language. To add this functionality, we’ll install the language switcher module that comes with Joomla.
1. Go to Extensions → Module Manager. Click New and create a new module of the Language Switcher type.
2. Enter a Title, ie Choose your language.
3. As the Position, select position-7.
4. The Language drop-down box should remain set to All, as this module will be displayed regardless of the selected language.
After you’ve saved the new module, have a look at the front end of the site. In the right column the language switch should be displayed.
Step 8 - Exploring the multilingual site
Congratulations, your modest but fully functional multilingual site is finished! When the user visits the site using a browser which is set to use the English language, Joomla will display the site with the English content: all articles and modules that have been
assigned English as their content language.
Should visitors wish to see the French version of the site contents, they can click the French flag icon in the Language Switcher.
Cat to: Tutorials Languages