Skip to main content

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 lang attribute 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 lang attribute of the <html> element at startup and follows every later change;
  • it uses the first two letters in lowercase. With pt-BR it uses pt, with zh-Hant it uses zh, with en-US it uses en;
  • 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 lang is empty or missing, it uses the web space's main language. If lang becomes 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.

GroupCodes
Included in the banneren, it, de
Downloaded from the version filesar, 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​

  1. In the dashboard, turn on the site's languages in Language management.
  2. Set the lang attribute on every page, for example <html lang="fr">.
  3. In the dashboard, turn on Automatically change the banner language, as the Cookie banner (in Italian) guide explains.
  4. 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_FR or FR: the banner uses the first two letters in lowercase;
  • with a value that is not a language code, for example xx or an empty string, the language does not change and the console shows a [Avacy] changeLanguage warning. The call does not throw errors;
  • when the language changes, the avacy:language-changed event 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 changeLanguage and a later change of lang.

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​

  1. Open the site in a private window. The banner appears and its texts are in the page language.
  2. Switch the site to another active language. The banner texts change too.
  3. 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 the lang attribute. 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.