Skip to content

i18n.md

Latest commit

 

History

History
226 lines (183 loc) · 6.86 KB

i18n.md

File metadata and controls

226 lines (183 loc) · 6.86 KB

Internationalization

The library includes complete translations for 10 languages, with automatic language detection and support for custom translations.

Supported Languages (10)

All language files are located in src/i18n/:

Language Code File Status
English en src/i18n/en.ts Complete
Spanish es src/i18n/es.ts Complete
German de src/i18n/de.ts Complete
French fr src/i18n/fr.ts Complete
Portuguese pt src/i18n/pt.ts Complete
Italian it src/i18n/it.ts Complete
Dutch nl src/i18n/nl.ts Complete
Polish pl src/i18n/pl.ts Complete
Japanese ja src/i18n/ja.ts Complete
Chinese (Simplified) zh src/i18n/zh.ts Complete

Additional files:

  • src/i18n/index.ts - Exports all translations and utilities
  • src/i18n/localeMapping.ts - Country-to-locale mapping

Automatic Language Detection

The library can automatically detect the user's language based on their location or browser settings. Configure this with the localeDetection option:

<ConsentProvider
  config={{
    localeDetection: 'auto',  // Detect from geo, then browser, then fallback
    defaultLocale: 'en',      // Fallback language
  }}
>

The detection modes are:

Mode Description
auto Try geo-detection first, then browser settings, then fallback to default
geo Detect only from geographic location
browser Detect from browser settings (navigator.language)
manual Use only the configured defaultLocale

When using geo or auto mode, the library maps countries to their primary language. For example, users in Spain, Mexico, or Argentina see Spanish. Users in Brazil or Portugal see Portuguese. Users in countries not specifically mapped see English.

Translation Structure

The library uses a comprehensive translation structure with the following sections:

Banner Section

banner: {
  title: string;              // "Cookie Settings"
  description: string;        // Main banner description
  acceptAll: string;          // "Accept All"
  rejectAll: string;          // "Reject All"
  customize: string;          // "Customize"
  privacyPolicy: string;      // "Privacy Policy"
  requiredServices: string;   // "Some services are required..."
  acceptRequired: string;     // "Accept Required"
  geoFallbackWarning: string; // Location detection warning
  shortAccept: string;        // "Accept" (short version for compact variants)
  shortReject: string;        // "Reject" (short version for compact variants)
  shortMore: string;          // "More" (for minimal variant)
  weUseCookies: string;       // "We use cookies." (for minimal variant)
  cookies: string;            // "cookies" (word for cookie counting)
}

Modal Section

modal: {
  title: string;           // "Cookie Preferences"
  description: string;     // Modal description
  save: string;            // "Save Preferences"
  acceptAll: string;       // "Accept All"
  rejectAll: string;       // "Reject All"
  close: string;           // "Close"
  alwaysActive: string;    // "Always Active"
  showServices: string;    // "View services"
  hideServices: string;    // "Hide services"
  domains: string;         // "Domains"
  requiredByAdmin: string; // "Required by site administrator"
  requiredReason: string;  // Required service explanation
}

Categories Section

categories: {
  necessary: { name: string; description: string; }
  functional: { name: string; description: string; }
  analytics: { name: string; description: string; }
  marketing: { name: string; description: string; }
  personalization: { name: string; description: string; }
}

Age Verification Section

ageVerification: {
  yearLabel: string;        // "Birth year:"
  dateLabel: string;        // "Birth date:"
  confirmButton: string;    // "Confirm age"
  goBack: string;           // "Go back"
  invalidYear: string;      // "Please enter a valid year"
  invalidDate: string;      // "Please enter your birth date"
  checkboxConfirm: string;  // "I confirm I am at least {age} years old"
}

Note: The {age} placeholder in checkboxConfirm is automatically replaced with the configured minimum age.

Custom Translations

You can override any translation or add new ones:

<ConsentProvider
  config={{
    translations: {
      en: {
        banner: {
          title: 'Cookie notice',
          description: 'We use cookies to improve your experience.',
          acceptAll: 'Accept',
          rejectAll: 'Decline',
          customize: 'Preferences',
          shortAccept: 'OK',
          shortReject: 'No',
        },
        categories: {
          analytics: {
            name: 'Analytics',
            description: 'Cookies that help us understand how you use our site.',
          },
        },
        ageVerification: {
          checkboxConfirm: 'I am {age} or older',
        },
      },
    },
  }}
>

Changing Language at Runtime

To change the language at runtime:

const { locale, setLocale } = useConsent();

// Get current locale
console.log(locale);  // 'en'

// Change to Spanish
setLocale('es');

Locale Utilities

You can also access locale utilities:

import {
  getAvailableLocales,
  isLocaleAvailable,
  getBestLocaleForCountry,
} from 'react-consent-shield';

// Get all available locales
getAvailableLocales();  // ['en', 'es', 'de', 'fr', 'pt', 'it', 'nl', 'pl', 'ja', 'zh']

// Check if a locale is supported
isLocaleAvailable('de');  // true
isLocaleAvailable('ja');  // true

// Get the best locale for a country
getBestLocaleForCountry('ES');  // 'es'
getBestLocaleForCountry('BR');  // 'pt'
getBestLocaleForCountry('JP');  // 'ja'
getBestLocaleForCountry('CN');  // 'zh'
getBestLocaleForCountry('NL');  // 'nl'
getBestLocaleForCountry('PL');  // 'pl'

Country-to-Locale Mapping

The library includes automatic country-to-locale mapping for over 100 countries:

Region Countries Primary Locale
East Asia Japan ja
East Asia China, Taiwan, Hong Kong, Macau zh
Europe Netherlands, Belgium, Suriname nl
Europe Poland pl
Europe Spain, Mexico, Argentina, etc. es
Europe Germany, Austria, Liechtenstein de
Europe France, Canada (Quebec), etc. fr
Europe Italy, San Marino, Vatican it
South America Brazil, Portugal, etc. pt
Global USA, UK, Australia, etc. en

Countries without a specific mapping default to English (en).

Back to main documentation | Previous: Audit Logging | Next: Styling