Localization

Some text comes from the components themselves rather than your props: button names such as "Clear selection", the "Optional" hint under a field, empty states, screen-reader announcements, and month and weekday names. Set a language once and all of it follows. Labels, placeholders and other text you pass as props stay as you wrote them.

The defaults shown on the component pages are the English texts.

Set the language

Colorffy UI ships English and Spanish. Pass a language pack and a locale when you install it:

import ColorffyUI from '@colorffy/ui'
import { es } from '@colorffy/ui/locales/es'
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).use(ColorffyUI, { locale: 'es-SV', labels: es }).mount('#app')

With the Nuxt module, name the pack in nuxt.config:

export default defineNuxtConfig({
  modules: ['@colorffy/ui/nuxt'],
  colorffyUI: {
    locale: 'es-SV',
    labels: 'es',
  },
})

locale sets the order you type dates in, the month and weekday names, and the first day of the week. Without it, components use the page's lang, then the browser's language.

Change a few texts

Your own texts merge over the pack, one group at a time, so you only write what differs:

app.use(ColorffyUI, {
  locale: 'es-SV',
  labels: {
    ...es,
    dateInput: { ...es.dateInput, apply: 'Listo' },
    common: { optional: '(opcional)' },
  },
})

Texts with placeholders keep them in braces, such as '{count} seleccionados' or 'Página {page} de {total}', so they also work as plain JSON in nuxt.config.

Which text wins

1. A prop on the component, such as clear-label or :labels on UiInputDate.
2. The nearest UiConfigProvider.
3. The plugin or Nuxt module options.
4. English.

<template>
  <UiInputDate v-model="snooze" time :labels="{ apply: 'Posponer' }" />
</template>

One section in another language

UiConfigProvider sets the locale and texts for everything inside it, merged over the surrounding ones:

<template>
  <UiConfigProvider locale="en-US" :labels="en">
    <PartnerPortal />
  </UiConfigProvider>
</template>

Switch language at runtime

useColorffyConfig() returns the app's live configuration. Set its locale and labels and every component updates in place, including an open calendar:

import { en } from '@colorffy/ui/locales/en'
import { es } from '@colorffy/ui/locales/es'

export default defineNuxtPlugin(() => {
  const { locale } = useI18n()
  const config = useColorffyConfig()

  watch(locale, (code) => {
    config.locale = code === 'es' ? 'es-SV' : 'en-US'
    config.labels = code === 'es' ? es : en
  }, { immediate: true })
})

Inside a UiConfigProvider, change its props instead.

Translate the date presets

The datePresets helpers show the datePresets texts in the current language, so a list defined once follows a language switch. A label you pass still wins:

const presets = [
  datePresets.today(),           // "Hoy"
  datePresets.lastDays(7),       // "Últimos 7 días"
  datePresets.thisMonth('Mes en curso'),
]

The time fields of UiInputDate are the browser's native ones, so they follow the browser's language and 12- or 24-hour clock rather than locale.

Singular and plural

A text with placeholders can also be a function that gets the same values and returns the text (LabelTemplate), for wording that changes with the number. The Spanish pack uses it for its summaries and date presets:

app.use(ColorffyUI, {
  labels: {
    ...es,
    multiSelect: { ...es.multiSelect, summary: ({ count }) => count === 1 ? '1 seleccionado' : `${count} seleccionados` },
  },
})

Props that take such a text, like maxChipsLabel, accept a function too. nuxt.config only holds plain values, so a function can't go in the module's colorffyUI.labels: name a pack there (labels: 'es'), or set the functions at runtime with useColorffyConfig() or a UiConfigProvider.

Use the labels in your own components

useLabels(group) returns one group's texts in the current language, with the same precedence the components use; pass a getter as the second argument to let your own props override them. formatLabel(text, values) fills the {placeholders}, or calls a function label with the values:

<script setup lang="ts">
import { formatLabel, useLabels } from '@colorffy/ui'

const props = defineProps<{ total: number, clearLabel?: string }>()
const texts = useLabels('multiSelect', () => ({ clear: props.clearLabel }))
const summary = computed(() => formatLabel(texts.value.summary, { count: props.total }))
</script>

<template>
  <span>{{ summary }}</span>
  <button type="button">{{ texts.clear }}</button>
</template>

Write a language pack

A pack is an object with every group. Type it with IColorffyLabels so the editor flags a missing or misspelled text:

import type { IColorffyLabels } from '@colorffy/ui'

export const fr = {
  common: { optional: 'Facultatif' },
  combobox: {
    empty: 'Aucun résultat',
    clear: 'Effacer la sélection',
    toggle: 'Afficher les options',
    loading: 'Recherche…',
    typeToSearch: 'Tapez pour rechercher',
    results: ({ count }) => (count === 1 ? '1 résultat' : `${count} résultats`),
  },
  pagination: { ariaLabel: 'Pagination', first: 'Première page', previous: 'Page précédente', next: 'Page suivante', last: 'Dernière page', status: 'Page {page} sur {total}' },
  // …every other group
} satisfies IColorffyLabels

The full list, with each text's English value, is in the IColorffyLabels type and in @colorffy/ui/locales/en.