i18n / Component Strings

All built-in text in Cocoar UI components — aria-labels, button labels, empty state messages, screen-reader announcements — defaults to English and can be translated without any extra setup.

How it works

Components use the useI18n() composable from @cocoar/vue-localization internally. If the localization plugin is not installed, every string falls back to its English default automatically. Nothing breaks, nothing needs to be configured.

Plugin not installed  →  English fallbacks (default)
Plugin installed      →  Translated strings, if the key exists in your JSON
Plugin installed, key missing  →  English fallback

Language switches are reactive — components re-render immediately when service.setLanguage() is called. No page reload required.

Setup

Install and configure @cocoar/vue-localization:

pnpm add @cocoar/vue-localization

// main.ts
import { createCoarLocalization } from '@cocoar/vue-localization';

app.use(createCoarLocalization({
  defaultLanguage: 'de',
  i18nUrl: (lang) => `/i18n/${lang}.json`,
}));

Your translation file at /i18n/de.json only needs to contain the keys you want to override — everything else stays English:

{
  "coar": {
    "ui": {
      "codeBlock": {
        "copy": "Kopieren",
        "copied": "Kopiert!",
        "failed": "Fehler"
      },
      "dialog": {
        "dialog": "Dialog",
        "close": "Schließen"
      },
      "tag": {
        "remove": "Entfernen"
      },
      "select": {
        "noResults": "Keine Ergebnisse",
        "noOptions": "Keine Optionen verfügbar",
        "clearSelection": "Auswahl löschen"
      },
      "pagination": {
        "nav": "Seitennavigation",
        "goToPage": "Zu Seite {page}"
      },
      "datePicker": {
        "dialog": "Datumsauswahl",
        "clearDate": "Datum löschen",
        "openPicker": "Auswahl öffnen",
        "jumpToToday": "Zum aktuellen Monat springen",
        "previousYear": "Vorheriges Jahr",
        "nextYear": "Nächstes Jahr",
        "months": "Monate"
      },
      "timePicker": {
        "hours": "Stunden",
        "minutes": "Minuten",
        "increaseHours": "Stunden erhöhen",
        "decreaseHours": "Stunden verringern",
        "increaseMinutes": "Minuten erhöhen",
        "decreaseMinutes": "Minuten verringern"
      },
      "toast": {
        "dismiss": "Benachrichtigung schließen",
        "notifications": "Benachrichtigungen"
      }
    }
  }
}

Key Reference

Each component's documentation page lists its translatable keys under an i18n Keys section. Check the component page you're working with for the exact keys available.

Interpolation

Some keys support {param} placeholders. The localization system replaces them automatically:

Key	Template	Result
coar.ui.pagination.goToPage	'Go to page {page}'	'Go to page 5'

In your translation file, use the same {page} placeholder:

{ "coar": { "ui": { "pagination": { "goToPage": "Zu Seite {page}" } } } }

Without @cocoar/vue-localization

If you only need to change a single string in one place, use the component's own props where available — for example CoarSpinner has a label prop, CoarPopconfirm has confirmText and cancelText. Check the component's Props table first before reaching for i18n.