Skip to main content

Banner language assignment logic

Updated

This article explains how the Usercentrics Consent Management Platform (CMP) determines which language it displays your consent banner in, how you can control that language yourself, and how to change it after the banner has already loaded.

There are two ways to set the banner's language:

Please note

Before you start: Any language you want to use must already be added to your configuration in the Admin Interface.

2. Strict assignment (force a specific language)

Use strict assignment if you run a region- or language-specific website that should always show the same language, regardless of who visits it.

To force a language, add the data-language parameter to your Usercentrics script tag. Replace {{language_code}} with your language's ISO 639-1 code (the standard two-letter language code — for example, "de" for German or "fr" for French). 

CMP version 3
CMP version 2
<script
  id="usercentrics-cmp"
  data-settings-id="XXXXXX"
  src="https://web.cmp.usercentrics.eu/ui/loader.js"
  data-language="de"
  async
></script>
<script
  type="application/javascript"
  src="https://app.usercentrics.eu/latest/main.js"
  data-language="de"
  id="XXXXXXXX"
></script

Once you set data-language, the banner always displays in that language. It won't follow the hierarchy described below.

2. Automatic assignment

Use automatic assignment if you run a single website that receives international traffic, is available in multiple languages, and you want the CMP to adapt to each visitor.

To enable this, implement your Usercentrics script without the data-language parameter. The CMP then determines the banner's language using this hierarchy:

  1. CDCS Local Storage: (the user’s language preference is transferred from another website that is connected to the current website via Usercentrics' Cross-Domain-Consent-Sharing iFrame)

  2. Website local storage: if the visitor has already chosen a language on this site during a previous visit (their browser's saved site data), the CMP uses that stored preference.
  3. The lang attribute on your <html> tag: for example, <html lang="de">.
  4. The visitor's browser language setting.
  5. Your Default Visible Language: set in the Admin Interface, used only if none of the visitor's preferred browser languages match a language you've configured.

Whichever language the CMP assigns, it saves that choice to the website's local storage. The visitor sees the same language on their next visit, unless they switch it using the CMP's language selector.

Tip for testing: To force the CMP to re-run the hierarchy instead of reusing a stored preference, clear your site's local storage or test in a private/incognito browser window.

Update the language after the banner has loaded

If your site changes language after the banner has already appeared — for example, a visitor navigates to a different-language version of your page — you can update the banner's language programmatically instead of waiting for a full reload.

CMP version 3
CMP version 2

window.__ucCmp.changeLanguage() is available, but it currently doesn't persist the change across page reloads and may not fully update Embeddings. This is a known limitation our engineering team is actively working on. Until it's resolved, use data-language for reliable language forcing on v3 rather than switching language on the fly.

Call UC_UI.updateLanguage() with the target language code:

UC_UI.updateLanguage("de");

If you're calling this before you're sure the script has finished loading, wrap it in a listener:

window.addEventListener("UC_UI_INITIALIZED", function() {
  UC_UI.updateLanguage("de");
});

Summary

Mode When to use it How to set it
Strict assignment Region- or language-specific sites that should always show one language Add data-language to your script tag
Automatic assignment A single site with international traffic, available in multiple languages Omit data-language and let the hierarchy decide