Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท SEO and Performance

Multilingual Sites

Build a multilingual Joomla site step by step: language packs, content languages, the Language Filter plugin, per-language menus, associations, switcher and hreflang.

Joomla has had multilingual support in the core for many years, and it is one of the reasons it is chosen for sites in several languages: a government portal, a tourism site, a company serving two markets. No extension is required, but the setup has several pieces that must fit together, and missing one gives confusing results (a page in the wrong language, a menu that disappears, no home page).

This lesson explains the pieces and the order to build them. Joomla cannot run on this site, so you get menu paths and two JavaScript stand-ins: a language resolver for URLs and a generator for hreflang links.

The idea

In a multilingual Joomla site:

  • Every piece of content (article, category, menu item, module) has a Language field: a specific language or All.
  • A language-specific Home page menu item exists for every language.
  • A plugin reads the language code in the URL (for example /de/) and filters everything to that language.
  • A language switcher module lets visitors move between versions.
  • Optional associations link the translations of one page to each other, so the switcher sends you to the translated page, not just the translated home.
flowchart TD
    U["Request /de/ueber-uns"] --> P["System - Language Filter plugin"]
    P --> L["Language = de-DE"]
    L --> M["Use German menu + Home"]
    L --> C["Show German articles and modules"]
    M --> R["Render page"]
    C --> R

The Language Filter plugin sets the language, and the rest of the site follows it.

Step-by-step setup

Work on a staging copy first, and keep the order below.

  1. Install the language packs. Go to System > Install > Languages, find each language (for example German and French) and install it. This installs translated interface strings for the site (front end) and, if you wish, the administrator. This does not translate your articles.
  2. Create content languages. Under System > Content Languages, New: choose the language, set a URL Language Code (de, fr), the Language tag and an optional image and publish it. These records say which languages your content uses. Also publish one for the default language.
  3. Enable the plugin. In System > Plugins enable System - Language Filter and open its options (see below). Without it nothing filters by language.
  4. Create a menu per language. For each language, make a menu (for instance Main Menu DE), and inside it a Home item (type Featured Articles or a single article) set as Default Home for that language: on the menu item, choose the language and mark it Home. Joomla demands one home per published content language.
  5. Create a menu module per language. Create a Menu module showing each language's menu, with its Language field set, and place it in the template position.
  6. Add the Language Switcher. Create a module of type Language Switcher and publish it. Choose options such as flags or language names, and whether to link to the associated page.
  7. Set the Language field on content. For each article, category and so on, select the language, or All for content that is shared.
  8. Associate translations (optional but recommended). Enable Multilingual Associations (it ships with the core) and the plugin System - Language Filter option Item Associations: Yes. Then edit an article, open the Associations tab and pick the translated version. Do the same for categories and menu items.

If a visitor gets a "Home page not found for language" message, a published content language has no home item.

Plugin options worth knowing

  • Automatic Language Change and Language Cookie: remember the visitor's language, or select it from the browser's Accept-Language.
  • Remove URL Language Code: removes the code for the default language only, so the main language lives at /about and others at /fr/about. A common choice that also keeps old URLs working.
  • Item Associations: yes, to make the switcher link to translated pages.
  • Add Alternate Meta Tag (hreflang): yes, to output <link rel="alternate" hreflang="..."> tags for associated pages.
  • Add x-default: a fallback hreflang for visitors whose language matches none.
JS Which language does a URL select?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last case shows that an unknown code falls through to the default language, which in real Joomla would typically become a 404 page for that path. This is a stand-in for the plugin's routing step.

Hreflang

hreflang tells search engines that several pages are translations of each other. Each page lists all versions, including itself, plus an optional x-default. Each link must be returned by the other pages too (they must point back), otherwise search engines ignore them. With associations and the plugin option on, Joomla generates them. To see the idea, build them yourself:

JS Generate hreflang tags

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Translating the interface and the details

  • Language overrides: change a single interface string (such as the "Read more" text) without editing files, in System > Language Overrides. Choose the language and client, search the constant and save.
  • Custom fields, tags and categories also have languages; keep taxonomy consistent across languages.
  • Right-to-left languages (Arabic, Hebrew, Persian): Joomla and Cassiopeia switch direction when the language pack is RTL.
  • SEO: use translated aliases (Unicode aliases for non-Latin scripts) and translated titles and descriptions, see SEO-Friendly URLs and Metadata.
  • Content workflow: decide who translates, how to mark a translation as outdated, and whether machine translation is acceptable. Joomla stores the translations; it does not translate for you.
  • Performance: the language filter adds filters to every query, so keep caching on and the number of languages realistic.

Troubleshooting

Symptom Likely cause
"Home page not found" A published content language has no Home menu item
Switcher goes to the home page only Associations are missing or the plugin option is off
Menu not visible Menu module language does not match, or access level wrong
Wrong language in URLs URL Language Code duplicated or the plugin's remove-code option conflicts
Content shows in all languages Item language set to All

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which plugin must be enabled for a Joomla multilingual site?

    The Language Filter plugin reads the URL language code and filters content, menus and modules.
  2. 2. What does installing a language pack translate?

    Language packs translate the system interface; your content must be written in each language.
  3. 3. What is the purpose of associations?

    Associations link the same page across languages and feed hreflang output.
  4. 4. A visitor sees 'Home page not found' for French. What is the usual cause?

    Each published content language needs its own default home item.

Summary

  • Multilingual support is built in: language packs, content languages, Language Filter plugin, per-language menus and Home, switcher module.
  • Every item has a Language field; use All for shared items.
  • Associations connect translations and enable proper switching and hreflang tags.
  • Use Remove URL Language Code for the default language if you want clean main-language URLs.
  • Use language overrides for small wording changes, and plan translation workflow and SEO per language.

Next: Component Structure and MVC