Guides

Internationalization

c15t ships with built-in translations for 30+ languages via the @c15t/translations package. Language detection happens automatically based on the browser's language preference, and you can override or extend translations for any language.

In c15t v2, the preferred config shape is i18n with locale, detectBrowserLanguage, and messages.

There are two ways c15t can load translations: client-side or server-side.

Server-side	Client-side
The best way to reduce bundle size and improve performance. We can detect the user's language based on the browser's language settings, allowing for the most accurate translations. By default, when using a inth.com hosted instance, these languages are supported.	Bundled with the application allowing for multiple languages to be supported without the need for a backend. The more translations you have, the larger the bundle size will be, which may impact the performance of your application.

Basic Configuration

Pass custom translations via the i18n option:

import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  i18n: {
    locale: 'en',
    messages: {
      de: {
        cookieBanner: {
          title: 'Datenschutzeinstellungen',
          description: 'Wir verwenden Cookies, um Ihnen das beste Erlebnis zu bieten.',
        },
        common: {
          acceptAll: 'Alle akzeptieren',
          rejectAll: 'Alle ablehnen',
          customize: 'Anpassen',
          save: 'Speichern',
        },
      },
    },
  },
});

Custom translations are deep-merged with built-in defaults — you only need to override the keys you want to change.

Translation Package Imports

Use the import path that matches your use case:

@c15t/translations: types, utilities, and enTranslations only (smallest client bundle)
@c15t/translations/en: English-only translation object
@c15t/translations/all: full baseTranslations map for all bundled locales

If you bundle translations client-side and need multiple languages, import from @c15t/translations/all explicitly:

import { baseTranslations } from '@c15t/translations/all';

const translations = {
  en: baseTranslations.en,
  de: baseTranslations.de,
  fr: baseTranslations.fr,
};

Translation Sections

The Translations object is organized into sections:

Section	Controls
`common`	Shared button labels: acceptAll, rejectAll, customize, save
`cookieBanner`	Banner title and description
`consentManagerDialog`	Dialog title and description
`consentTypes`	Per-category title and description (keyed by AllConsentNames)
`frame`	Frame placeholder title and button text (supports `{category}` placeholder)
`legalLinks`	Privacy policy, cookie policy, terms of service link text
`iab`	IAB TCF banner, preference center, vendor list translations

Changing Language

Switch the active language at runtime with setLanguage():

const state = consentStore.getState();

// Switch to German
await state.setLanguage('de');

// Build a language switcher
document.getElementById('lang-select')?.addEventListener('change', async (e) => {
  const lang = (e.target as HTMLSelectElement).value;
  await consentStore.getState().setLanguage(lang);
});

setLanguage() re-fetches the consent banner to get server-resolved translations for the new language.

Automatic Language Detection

By default, c15t detects the browser's language (navigator.language) and selects the closest matching translation. If custom messages are configured, fallback stays within your configured languages before using locale (or 'en') as the preferred fallback language.

When backend policy packs use i18n.messageProfile, the active language pool comes only from that resolved profile.

Example: if your Europe profile defines en, fr, and de, and your default profile defines en, es, and pt, a Europe visitor can resolve to en, fr, or de, but not es, pt, or zh.

Use profile-local fallbackLanguage inside backend i18n.messages to choose which configured language a policy profile should fall back to when the browser asks for an unsupported locale.

Disable auto-detection to always use locale:

i18n: {
  locale: 'de',
  detectBrowserLanguage: false,
  messages: { ... },
}

If you need a policy to always use one specific language regardless of browser preference, set policy.i18n.language on the backend policy pack.

Override the title and description for individual consent categories:

i18n: {
  messages: {
    en: {
      consentTypes: {
        measurement: {
          title: 'Analytics & Performance',
          description: 'Help us understand how visitors interact with our site.',
        },
        marketing: {
          title: 'Advertising',
          description: 'Used to deliver relevant ads and measure campaign effectiveness.',
        },
      },
    },
  },
}

Legacy `translations` Compatibility

The legacy syntax is still supported in 2.0 for RC compatibility:

// Legacy (still supported)
translations: {
  defaultLanguage: 'en',
  disableAutoLanguageSwitch: true,
  translations: { ... },
}

// Preferred in v2
i18n: {
  locale: 'en',
  detectBrowserLanguage: false,
  messages: { ... },
}

If both are provided, i18n takes precedence.