Banner language on multilingual sites
The banner can show its texts in the page language, with a dashboard setting. This page explains how it works and which languages exist.
Prerequisites
Before you start, check that:
- the banner is installed on the page. See HTML snippet;
- every page has the
langattribute on the<html>element, for example<html lang="fr">; - the page language is among the web space's active languages in the dashboard. With a language that is not active, the banner uses English, if it is among the active languages, otherwise the main language.
Automatic detection
You turn on detection in the dashboard with Automatically change the banner language, in Text management, under Language preferences. The instructions are in the Cookie banner (in Italian) guide.
With the setting on, the banner behaves like this:
- it reads the
langattribute of the<html>element at startup and follows every later change; - it uses the first two letters in lowercase. With
pt-BRit usespt, withzh-Hantit useszh, withen-USit usesen; - if the language is among the web space's active languages, it shows the texts in that language. If you haven't customised the texts for that language, it uses Avacy's default texts;
- if the language is not among the active languages, it uses English, if it is among the active languages, otherwise the web space's main language;
- at startup, if
langis empty or missing, it uses the web space's main language. Iflangbecomes empty later, the language does not change.
With the setting off, the banner always uses the web space's main language, whatever lang is.
Available languages
The banner includes three languages in its code: en, it and de. Another 32 languages come from the banner version files, and with the HTML snippet the banner downloads the file it needs by itself.
| Group | Codes |
|---|---|
| Included in the banner | en, it, de |
| Downloaded from the version files | ar, bg, bs, ca, cs, cy, da, el, es, eu, fi, fr, gl, he, hr, hu, id, ja, ko, lt, lv, mk, mt, nl, no, pl, pt, ro, ru, sl, uk, zh |
For a language that is active in the web space but missing from the table, for example tr or sv, the banner shows the texts in English, so it doesn't mix two languages. With a valid language code, the browser console reports an error on the language file, usually 403 or 404.
For active languages the banner uses the default texts, even if you haven't customised the texts in the dashboard. Custom texts apply to the language you wrote them in.
Steps
- In the dashboard, turn on the site's languages in Language management.
- Set the
langattribute on every page, for example<html lang="fr">. - In the dashboard, turn on Automatically change the banner language, as the Cookie banner (in Italian) guide explains.
- Publish the change on the site.
When you change the active languages or the main language in Language management, the dashboard republishes the banner by itself. The banner uses the new list from the next visit, without another publish.
Changing the language from code
If the site does not update lang, for example in a single-page application, change the banner language with window.Avacy.changeLanguage.
window.Avacy.changeLanguage('fr');
How the call works:
- it also accepts
fr-FR,fr_FRorFR: the banner uses the first two letters in lowercase; - with a value that is not a language code, for example
xxor an empty string, the language does not change and the console shows a[Avacy] changeLanguagewarning. The call does not throw errors; - when the language changes, the
avacy:language-changedevent fires (see Banner events); - the change does not survive a page reload: at startup the banner starts again from the main language or, with automatic detection, from
lang; - with automatic detection on, the last change wins, between
changeLanguageand a later change oflang.
The same rules as automatic detection apply. With a language that is not active in the web space, the banner uses English, if it is among the active languages, otherwise the main language. With an active language that has no text file, for example sv, it shows English.
Check
- Open the site in a private window. The banner appears and its texts are in the page language.
- Switch the site to another active language. The banner texts change too.
- Open a page in a language that is not active. The banner is in English, if English is among the active languages, otherwise in the main language.
Common problems
The most frequent problems:
- The banner is in Italian on a page in another language: check that Automatically change the banner language is on and that
<html>has thelangattribute. Also check that the page language is active in the web space: with a language that is not active, the banner uses English, if it is among the active languages, otherwise the main language; - The banner is in English or in the main language instead of the page language: the page language is not active in the web space. Turn it on in the dashboard, in Language management, as the guide to enabling a language (in Italian) explains. The dashboard republishes the banner by itself;
- The banner is in English on a page in another active language: the language is not in the table, or the language file did not download (403 or 404 error in the console).
Last updated: 09/11/2026.