Building Multilingual Websites in Joomla 4
Joomla 4 is one of the best CMS selections for multilingual (multi language) support. Joomla 4 allows your website to support multiple languages out of the box, without the need for any third-party extensions.
In this guide, you will learn how to configure language settings, create language overrides, and setup Joomla to show your content in multiple languages.
Joomla 4 itself has been translated into dozens of different languages. These language files can be installed by navigating to System Manage Languages.
The Languages management page displays all the languages currently installed on your website. These are the languages the Joomla interface may be translated into.
Note that the language selected here applies to your website's forms, fields, labels, and interface only. It will not automatically translate the actual content of your website.
You may click Install Languages in the toolbar to add additional languages. You should install any languages you intend to allow your users to use on the website. For example, if you plan on targeting English and Spanish users, install English and Spanish.
Some languages, like English, have multiple variants for different countries available. You should select the primary variant of your expected user base. It is up to you to decide if you want to install multiple variants of the same language. I usually do not do this, as I know people in the UK can read US English just fine, and vice versa. There are only some slight grammatical variances, so I don't think it warrants installing both versions.
If you accidentally selected the wrong variant when you installed Joomla, (e.g. English, UK instead of English, US) you may decide to change the variant used.
Just navigate the list, find your language, and click the Install button. Joomla will download the required language files.
Note that it takes time for contributors to update the Joomla language files. They rely on the community for these updates. Each time a new version of Joomla is released, new fields and options may be created. If the version of the language does not match the current version of Joomla, that is okay. 99.9% of the fields will still be translated properly. This is why some of the language versions have a yellow background behind them, while others are green.
After installing your language, you may set it as the new default by clicking the star icon in the languages manager. To change the language for your current user account, you will have to set your language under the basic settings tab of your user account in the User Manager.
Language is set for the frontend (site) and backend (admin panel) individually. I have set both my languages to Spanish (Spain), for demonstration purposes.
Here's what my backend looks like when I change it to Spanish. Note that all menus, buttons, and fields will display in Spanish. My content itself, the site title, etc. are still in English.
The help documentation pages do not automatically change to Spanish, as they're written in English on joomla.org.
It's possible to override the individual text of any element in Joomla using a language override. To do this, navigate to System Manage Language Overrides.
This page displays the language override constants for the frontend and backend of every installed language. In Joomla, every field is represented by a constant. Every constant is associated with a text value, depending on which language you're using.
For example, the constant COM_CONFIG_GLOBAL_CONFIGURATION is associated with the value "Global Configuration" in English. In Spanish, the same constant is associated with the value "Configuración global," the Spanish equivalent of Global Configuration.
To override the text of any element in Joomla, first select the language and location (frontend or backend) you want to work with. Then, click New to create a new language override.
Unless you're a Joomla developer, or have previously overridden a specific constant, you likely don't know the exact name of the constant you want to override. This page provides a search feature which allows you to find the constant you need to override.
Just search for existing text you want to override. For example, if I wanted to rename the text Joomla uses to display the word "Yes" I can search for the value yes, and find the constant it's associated with.
Note that many words and phrases are associated with multiple constants, so you will have to override each constant, or figure out what specific instance you need to override.
After searching for the text "Yes" I could identify the constant I need to use. It's JYES.
Copy the language constant.
Paste the language constant into the Edit This Override section. Then, type whatever new value you would like to use. In this case, I'm replacing "Yes" with "Yeah".
If you select the checkbox that says "For Both Locations," the language override will apply to both the frontend and backend for this item.
Save it when you're done.
Now, wherever I would usually see the word "Yes," such as in many options screens, it will say "Yeah" instead.
It's also possible to create multiple versions of all your pages/content to be specific to different languages. For example, if you're bilingual, you could create an article in English, create a separate version of the same article in Spanish, and then allow users to select whether they want to read the English version or the Spanish version.
Joomla does not automatically translate the text of content for you, nor should it, if you want the best translation possible (human translation). I wouldn't suggest using something like Google translate to translate your content, as it might not be 100% accurate or readable by users. If you're going to go that route, a faster option would be to just leave your website in English and have users use their own translation extensions.
Note that this is a pretty large undertaking. For this to work best, you must create multiple versions of every piece of content you add for each language you want to support. For example, if you have 10 articles in English, and want to allow Spanish and French users to read it, you'd have to create a total of 30 articles, three articles for each of the three languages. You'll also have to spend more time setting this all up and linking the different versions together.
Getting Set Up
In order to enable multilingual content support, you must first configure some settings. You'll have to enable the different languages, create a different menu for each language, and provide users with a way to switch between the languages. Then, you'll have to create variants for each article you want to display in a different language, and link them together through associations.
Enable The Content Language
Begin by navigating to System Manage Content Languages. in the backend. Make sure the language you want to support is installed. If it's not, install it by clicking the Install Languages button.
You must enable each language you plan on supporting by clicking the option under Status next to each item. In this example, I'm adding Spanish as a supported language.
If you open any of the languages on the Content Languages page, you can edit additional settings about that content language such as the flag image used and the language code shown in URLs.
Notably, in the options tab, you can change the name of your site to be language specific.
Enable The Language Filter Plugin
Next, make sure the language filter plugin is enabled. This is a system plugin that adds multilingual content support.
Navigate to to System Manage Plugins. and search for the "Language Filter" plugin.
This plugin contains some settings you may want to change, though the defaults will suffice for most use cases.
- Language Selection - The language to use for new users
- Automatic Language Change - Automatically changes the content language based on the user's site language preference. This prevents your interface from showing in English, and your content in Spanish, for example.
- Item Associations - Allows us to associate items when switching languages, recommended set to yes.
- Add Alternative Meta Tags - Use different meta tags for the different language variants. Recommended set to yes.
- x-default: This should be set to the default language used on your website.
- Remove URL Language Code - remove the language code from the page address. Recommended set to no, to avoid confusion.
- Cookie lifetime - How the system remembers the language of guests - it's tied to their current browser session, or remains the same for an entire year.
Make sure this plugin is enabled and save it.
Multilingual Status Module
After enabling the language filter plugin, a new module will be displayed in the topmost toolbar (status area) of the admin dashboard. Clicking this will bring up a window displaying information about the multilingual status of your website. This will instruct you on what's missing to make your website compatible with multiple languages.
As you can see, there are quite a few steps left to go.
Create Multiple Menus
Now we have to create a new menu for each language we plan on supporting. Navigate to System Menus and create a new menu (not a new menu item, an entirely new menu).
Give your new menu an appropriate name and save it. I've called mine "Main Menu (es)" so I know it's the Spanish menu. Save the new menu.
Now, add another menu for your primary language. I've called this "Main Menu (en)"
When completed, you should have three main menus. A default main menu, an English main menu, and a Spanish main menu (or whichever languages you selected).
Create Home Pages
You'll now have to create a separate home page link in each menu, for each language. I've decided to use the menu item type "Featured Articles" for my home pages, but you may use whatever menu item type you want. If your home page is a single article, we'll create links to the different versions later.
Open each menu and create a new home page item within each one. You will have to use different menu item aliases for each. I've left my default alias as "home," my Spanish version set to "principal" and my English version set to "home-en". I titled my home pages "Home" "Página Principal" and "Home" respectively.
Note that I'm not a native Spanish speaker, but I think página principal is a term used to refer to the home page (major/principle page).
Ensure that you set the Language field to the proper language for this page.
After creating a home page for each language-specific menu, you need to set them as the home pages. You can only set one home page per menu, which is why we needed 3 different menus. One home page for the default/international menu, one for the English menu, and one for the Spanish menu.
Just click the icon under the home column for respective menu's new home page. If you set the language field properly in the menu item, a flag representing the language should be displayed next to the menu item.
Publish the Language Switcher Module
Next, go to the module manager for site modules and create a new Language Switcher module. This is the module users may use to switch between different content languages on your site.
The options may be configured to change the way the module is displayed. By default, it will display the flag icons for each respective language, and clicking these icons will switch the language.
Make sure you assign it to a position where it will be visible, then save and publish it.
Now when I visit my site's frontend, I can see the language switcher and switch between languages. If I select Spanish, my home page is now the "Página Principal" page instead of the "Home" page.
Note that the text of the interface fields, like the login box switched to Spanish, but the module titles and main menu at the top did not. This is because modules must be set individually per language, if you want them to be displayed for a certain language. This means if I want my Spanish menu to be displayed, I'll have to create a duplicate main menu module for the Spanish version.
Language Specific Modules
I'm going to create a different version of my main menu, so it's specific to Spanish speaking users. I'm also going to set my default main menu module to the English language and direct it to my English menu.
You should now have a separate menu for Spanish speaking users and English speaking users. Note that you do not want to create a third menu module with the "all" languages option, or you will see this extra menu on both the Spanish and English views of your website.
Now, when I reload my frontend with Spanish selected, the Spanish menu is displayed at the top of my page instead of the English menu. If I switch to English, the menu switches back to English.
To change the title of the login form, you would again have to create a separate login form for English speaking users and Spanish speaking users, then set the language option appropriately for each one. Alternatively, you can use the "all" option and hide the title of the module, then assume users know it's a login form. That way, your Spanish speaking users don't see the words "Login Form" in English.
Content and Associations
Next, we're going to learn how to create a Spanish and English version of the same article, then display that article on the respective Spanish and English version of the website.
To do this, first write an article in English, as you normally would. Then, set its language to English.
Now if I visit my front end, the English article shows up if I'm using the English language, and nothing shows up if I select the Spanish language.
To create a Spanish version of my article, I'm going to start from the English version and create an association. Associations are links between items of different languages. Joomla supports creating associations between menu items, articles, categories, contacts, and more.
Open the original version of the article you'd like to create a different version of. In the topmost toolbar, there's a button that says Associations. Click this option.
A new page will display showing the original version of the article in its language, and a new version of the article in your target language. Choose a target language. In this case, I'm going from English to Spanish, so my target will be Spanish.
If you've already created a version of the article in both languages, you can choose the Select Target button to pick the article in the target language.
You may begin writing the translated article in the right. You may also start by copying the reference to the target, using the button at the top. This may be useful if the original article contains images and content/layouts that you need to preserve, before editing the text.
Once you are done translating the article, you need to save the target, and save the reference to the target. So click Save Target and then Save Reference.
If you return to the article manager, you should see both articles - one in each language. Additional details are displayed with the language of each article, along with what languages the article is associated with. In this example, the English article is associated with the Spanish, and vice versa.
Now, when I visit my home page, I can switch between the two languages and see the respective article in the correct language. If I open each article individually, and then select the Language, Joomla knows which article is associated with which language, and displays the proper version.
Suggested Practices and Additional Notes
Associations may be created with menu items the same way they are for articles. Just open the menu item and click Associations at the top of the page. I would recommend you create an associated menu item corresponding to every other item in your menu. If you do not do this, Joomla will not know what page to take the user to when they switch languages, and the user will be redirected to the home page for the selected language, rather than to the correct version of the page they're currently on.
You aren't required to create associations between articles, or multiple versions of every article, if you do not want to. The site will still work fine, except certain articles will only be visible to users who select that language. For example, if your website has articles that are specific to Spanish-speaking users, and do not apply to English-speaking users, you may not want to create the English version.
You may view all the associations created by navigating to Components Multilingual Associations in the admin menu.