Translations for JavaScript

Every text the SDK shows comes from one translation map, in English by default. You can swap in a shipped language, write your own, or change a single string. All of it goes through the i18n option of the configuration.

The examples use @cookieyes/vanilla. Every text in its banner and dialogs, including the screen-reader labels, comes from this map. The same i18n works in initCookieYes() from @cookieyes/core, for a UI of your own.

Use a shipped language

English is built in. Spanish, French, German and Italian ship in @cookieyes/translations; import the one you need and pass it in.

import { fr } from "@cookieyes/translations/fr";
import { start } from "@cookieyes/vanilla";

start({
  mode: "cookie-only",
  i18n: {
    locale: "fr",
    messages: { fr },
  },
});

Import each language from its own path, as above, so only the languages you use end up in your bundle.

Change any text

Set only the keys you want to change. Everything else stays English, so one key is enough:

import { start } from "@cookieyes/vanilla";

start({
  mode: "cookie-only",
  i18n: {
    messages: {
      en: {
        bannerTitle: "We value your privacy",
        acceptAll: "Sounds good",
        categories: {
          analytics: { label: "Statistics", description: "Helps us see which pages are useful." },
        },
      },
    },
  },
});

The same works for any language: add the key under messages.fr, for example, and it replaces that string in French only.

Let visitors switch language

Bundle the languages you offer, then call setLanguage() from your own picker. The SDK does not remember the choice between visits; store it yourself and pass it back as locale.

import { cookieyes } from "./consent";

const picker = document.querySelector<HTMLSelectElement>("#language");

picker?.addEventListener("change", async () => {
  await cookieyes.consentStore.setLanguage(picker.value);
  localStorage.setItem("language", picker.value);
});

cookieyes is the runtime start() returned, exported from your consent file as in Banner with no framework. cookieyes.consentStore.getLanguageInfo() lists the languages you bundled.

To load a language only when it is chosen, give i18n a loadLanguage function. The SDK calls it once per language the first time that language is needed:

import { start } from "@cookieyes/vanilla";

start({
  mode: "cookie-only",
  i18n: {
    loadLanguage: async (tag) => (await import(`@cookieyes/translations/${tag}`))[tag],
  },
});

On a site where the URL carries the language, call setLanguage() with the tag from the URL and set detectBrowserLanguage: false.

Good to know

The browser language is used by default. With messages: { fr } and no locale, a visitor whose browser is French sees French and everyone else sees English. Set detectBrowserLanguage: false to always use locale.

Regional tags fall back to the language. A visitor on fr-CA gets your fr.

Your own code can read the text. consentStore.translations is the active language's map; consentStore.subscribe() tells you when it changes.

Right-to-left languages. The @cookieyes/vanilla banner always renders left to right. For Arabic, Hebrew or another right-to-left language, build your own UI and set dir from consentStore.getLanguageInfo().direction.

Common mistakes

locale: "fr" still shows English. fr is not in messages. Import the catalog and add it.

The banner is in the browser's language, but you wanted one fixed language. Set detectBrowserLanguage: false.

A changed key has no effect. The key path is wrong. Keys are nested: optOut.title, not optOutTitle; category text is categories.<id>.label.

setLanguage() seems to do nothing. It is async, and it warns in the console if the language is not in messages and no loadLanguage is set. Await it and check the console.

Next steps

• Configuration: the i18n option in the reference table