Internationalization (i18n)

pnpm add @friendlyinternet/nuxt-crouton-i18n

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-i18n'
  ]
})

// crouton.config.js
export default {
  translations: {
    collections: {
      products: ['name', 'description'],  // These fields are translatable
      posts: ['title', 'body', 'excerpt']
    }
  }
}

<!-- Auto-generated when using --no-translations=false -->
<template>
  <UForm @submit="handleSubmit">
    <!-- Regular fields -->
    <UFormField label="SKU" name="sku">
      <UInput v-model="state.sku" />
    </UFormField>

    <!-- Translatable fields -->
    <CroutonI18nInput
      v-model="state.translations"
      :fields="['name', 'description']"
      :default-values="{
        name: state.name,
        description: state.description
      }"
    />
  </UForm>
</template>

<script setup lang="ts">
const { locale } = useI18n()

// Auto-fetches for current locale
const { items } = await useCollectionQuery('shopProducts', {
  query: computed(() => ({ locale: locale.value }))
})

// Auto-refetches when locale changes!
</script>

<script setup lang="ts">
const { t } = useEntityTranslations()
const product = { name: 'Product', translations: { fr: { name: 'Produit' } } }
</script>

<template>
  <!-- Shows "Product" in English, "Produit" in French -->
  <div>{{ t(product, 'name') }}</div>
</template>

1. nuxt-crouton/i18n/locales/           (Crouton component strings)
2. nuxt-crouton-supersaas/i18n/locales/ (App-level strings from SuperSaaS package)
3. layers/[domain]/i18n/locales/        (Domain-specific strings)
4. app/i18n/locales/                    (App-level overrides)
5. Database (translationsUi table)      (Runtime overrides)

1. DB: Team override for current team?
   ↓ (not found)
2. DB: System default?
   ↓ (not found)
3. Locale files (merged, last wins):
   a. nuxt-crouton/i18n/locales/en.json
   b. nuxt-crouton-supersaas/i18n/locales/en.json
   c. layers/bookings/i18n/locales/en.json
   d. app/i18n/locales/en.json (if exists)
   ↓ (found in supersaas)
4. Return value: "Save"

pnpm crouton i18n seed

# Seed all locales
pnpm crouton i18n seed

# Seed specific locale
pnpm crouton i18n seed --locale=en

# Force overwrite existing
pnpm crouton i18n seed --force

# Dry run (show what would be inserted)
pnpm crouton i18n seed --dry-run

// Built-in configuration
{
  locales: [
    { code: 'en', name: 'English', file: 'en.json' },
    { code: 'nl', name: 'Nederlands', file: 'nl.json' },
    { code: 'fr', name: 'Français', file: 'fr.json' }
  ],
  defaultLocale: 'en',
  strategy: 'no_prefix'
}

export default defineNuxtConfig({
  extends: [
    '@friendlyinternet/nuxt-crouton',
    '@friendlyinternet/nuxt-crouton-i18n'
  ],

  i18n: {
    locales: [
      { code: 'en', name: 'English', file: 'en.json' },
      { code: 'es', name: 'Español', file: 'es.json' },
      { code: 'de', name: 'Deutsch', file: 'de.json' }
    ]
  }
})

// layers/my-layer/nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    locales: [
      { code: 'en', file: 'en.json' },
      { code: 'nl', file: 'nl.json' },
      { code: 'fr', file: 'fr.json' }
    ],
    langDir: './locales'  // ✅ Relative to restructureDir 'i18n'
  }
})

layers/my-layer/
├── i18n/
│   └── locales/
│       ├── en.json
│       ├── nl.json
│       └── fr.json
└── nuxt.config.ts

interface DisplayProps {
  translations: Record<string, string>  // Translation values by locale
  languages?: string[]                   // Override available languages
}

<script setup lang="ts">
const product = {
  name: 'Product',
  translations: {
    en: 'English Product Name',
    nl: 'Nederlandse Productnaam',
    fr: 'Nom du produit français'
  }
}
</script>

<template>
  <!-- Basic usage -->
  <CroutonI18nDisplay :translations="product.translations" />

  <!-- Custom languages -->
  <CroutonI18nDisplay
    :translations="product.translations"
    :languages="['en', 'nl']"
  />
</template>

interface InputProps {
  modelValue: SingleFieldValue | MultiFieldValue | null
  fields: string[]                          // Fields to translate
  label?: string                            // Form label
  error?: string | boolean                  // Validation error
  defaultValues?: Record<string, string>    // Default values for fallback
  fieldComponents?: Record<string, string>  // Custom components per field
}

type SingleFieldValue = Record<string, string>
type MultiFieldValue = Record<string, Record<string, string>>

<script setup lang="ts">
const state = ref({
  name: '',
  translations: {} // { en: "English", nl: "Nederlands", fr: "Français" }
})
</script>

<template>
  <CroutonI18nInput
    v-model="state.translations"
    :fields="[]"
  />
</template>

<script setup lang="ts">
const state = ref({
  name: 'Product',
  description: 'Description',
  translations: {} // { en: { name: "...", description: "..." }, nl: { ... } }
})
</script>

<template>
  <CroutonI18nInput
    v-model="state.translations"
    :fields="['name', 'description']"
    :default-values="{
      name: state.name,
      description: state.description
    }"
  />
</template>

<script setup lang="ts">
const state = ref({
  title: '',
  content: '<p></p>',
  translations: {}
})
</script>

<template>
  <CroutonI18nInput
    v-model="state.translations"
    :fields="['title', 'content']"
    :default-values="{
      title: state.title,
      content: state.content
    }"
    :field-components="{
      content: 'CroutonEditorSimple',  // Rich text editor
      title: 'UInput'                   // Default input
    }"
  />
</template>

interface InputWithEditorProps {
  modelValue: Record<string, string>  // Translation values
  fields: string[]                     // For backwards compatibility
  label?: string
  error?: string | boolean
  useRichText?: boolean                // Enable rich text editor
}

<script setup lang="ts">
const state = ref({
  content: '<p>English content</p>',
  translations: {}
})
</script>

<template>
  <!-- With rich text editor -->
  <CroutonI18nInputWithEditor
    v-model="state.translations"
    :fields="['content']"
    :use-rich-text="true"
  />

  <!-- Plain text input -->
  <CroutonI18nInputWithEditor
    v-model="state.translations"
    :fields="['content']"
    :use-rich-text="false"
  />
</template>

{
  en: '🌹',  // English
  nl: '🦁',  // Dutch
  fr: '🐔'   // French
}

<template>
  <!-- Basic usage -->
  <CroutonI18nLanguageSwitcher />
</template>

<template>
  <!-- Floating switcher in top-right -->
  <CroutonI18nLanguageSwitcherIsland />
</template>

interface UiFormProps {
  action: 'create' | 'update' | 'delete'
  activeItem?: any                       // Item being edited
  loading?: string                       // Loading state
  collection: string                     // Collection name
}

<script setup lang="ts">
const action = ref<'create' | 'update' | 'delete'>('create')
const activeItem = ref(null)
</script>

<template>
  <CroutonI18nUiForm
    :action="action"
    :active-item="activeItem"
    collection="translationsUi"
  />
</template>

[
  { key: 'keyPath', label: 'Key Path' },
  { key: 'category', label: 'Category' },
  { key: 'values', label: 'Translations' },
  { key: 'description', label: 'Description' },
  { key: 'actions', label: 'Actions' }
]

<template>
  <CroutonI18nUiList />
</template>

interface CardsMiniProps {
  locale: string        // Locale code (en, nl, fr)
  hasTranslation: boolean  // Whether translation exists
}

<template>
  <CroutonI18nCardsMini locale="en" :has-translation="true" />
  <CroutonI18nCardsMini locale="nl" :has-translation="false" />
</template>

interface ListCardsProps {
  item: any           // Entity with translations
  fields: string[]    // Fields to check for translations
}

<script setup lang="ts">
const product = {
  translations: {
    en: { name: 'Product', description: 'Description' },
    nl: { name: 'Product' }  // description missing
  }
}
</script>

<template>
  <CroutonI18nListCards
    :item="product"
    :fields="['name', 'description']"
  />
  <!-- Shows: EN (complete), NL (incomplete), FR (missing) -->
</template>

<template>
  <!-- Add to your layout for dev mode -->
  <CroutonI18nDevModeToggle />
</template>

interface DevWrapperProps {
  translationKey: string     // Translation key path
  value?: string              // Current value
  locale?: string             // Current locale (default: 'en')
  level?: 'system' | 'team' | 'missing'  // Translation source
  teamId?: string             // Team ID for team translations
}

<script setup lang="ts">
const { currentTeam } = useTeam()
</script>

<template>
  <!-- Wrap translatable content -->
  <CroutonI18nDevWrapper
    translation-key="common.save"
    :value="$t('common.save')"
    level="system"
  >
    {{ $t('common.save') }}
  </CroutonI18nDevWrapper>

  <!-- Team-specific translation -->
  <CroutonI18nDevWrapper
    translation-key="dashboard.title"
    :value="title"
    level="team"
    :team-id="currentTeam?.id"
  >
    {{ title }}
  </CroutonI18nDevWrapper>
</template>

interface TranslationOptions {
  params?: Record<string, any>
  fallback?: string
  category?: string
  mode?: 'system' | 'team'
  placeholder?: string
}

function useT(): {
  t: (key: string, options?: TranslationOptions) => string
  tString: (key: string, options?: TranslationOptions) => string
  tContent: (entity: any, field: string, preferredLocale?: string) => string
  tInfo: (key: string, options?: TranslationOptions) => TranslationInfo
  hasTranslation: (key: string) => boolean
  getAvailableLocales: (key: string) => string[]
  getTranslationMeta: (key: string) => TranslationMeta
  refreshTranslations: () => Promise<void>
  locale: Ref<string>
  isDev: boolean
  devModeEnabled: Ref<boolean>
}

<script setup lang="ts">
const { t, tString, tContent } = useT()

// Basic translation
const saveLabel = t('common.save')

// With parameters
const greeting = t('messages.hello', {
  params: { name: 'John' }
})

// String-only (for non-template contexts)
const title = tString('page.title')

// Entity field translation
const productName = tContent(product, 'name')
</script>

<script setup lang="ts">
const { t } = useT()
const { currentTeam } = useTeam()

// 1. Checks team translations for current team
// 2. Falls back to system translation
// 3. Returns [key] if not found
const label = t('dashboard.welcome')
</script>

<template>
  <h1>{{ label }}</h1>
</template>

<script setup lang="ts">
const { tContent } = useT()
const { locale } = useI18n()

const product = {
  name: 'Product',
  translations: {
    en: { name: 'English Name', description: 'English Description' },
    nl: { name: 'Nederlandse Naam' }
  }
}

// In English: "English Name"
// In Dutch: "Nederlandse Naam"
// In French: "English Name" (fallback)
const name = tContent(product, 'name')

// With explicit locale
const dutchName = tContent(product, 'name', 'nl')
</script>

function useEntityTranslations(): {
  t: (entity: any, field: string) => string
}

<script setup lang="ts">
const { t } = useEntityTranslations()
const { locale } = useI18n()

const product = {
  name: 'Product',
  description: 'English description',
  translations: {
    nl: {
      name: 'Product',
      description: 'Nederlandse beschrijving'
    }
  }
}

// Automatically uses current locale
const name = t(product, 'name')
const description = t(product, 'description')
</script>

<template>
  <div>
    <h2>{{ name }}</h2>
    <p>{{ description }}</p>
  </div>
</template>

// Priority:
// 1. translations[currentLocale][field]
// 2. entity[field] (root field value)
// 3. Empty string

const product = {
  name: 'Default Name',
  translations: {
    nl: { name: 'Nederlandse Naam' }
  }
}

// In NL locale: "Nederlandse Naam"
// In EN locale: "Default Name" (fallback to root)
// In FR locale: "Default Name" (fallback to root)
t(product, 'name')

function useTranslationsUi(): {
  schema: ZodSchema
  columns: ColumnDefinition[]
  defaultValue: TranslationDefaults
  defaultPagination: PaginationConfig
  config: CollectionConfig
  collection: string
}

<script setup lang="ts">
const { schema, columns, defaultValue } = useTranslationsUi()

const state = ref({ ...defaultValue })

const handleSubmit = async () => {
  const valid = schema.parse(state.value)
  await $fetch('/api/translations-ui', {
    method: 'POST',
    body: valid
  })
}
</script>

<template>
  <UForm :schema="schema" :state="state" @submit="handleSubmit">
    <UFormField label="Key Path" name="keyPath">
      <UInput v-model="state.keyPath" />
    </UFormField>
    <!-- ... -->
  </UForm>
</template>

{
  id: string (primary key)
  userId: string (not null)
  teamId: string (nullable)  // null = system translation
  namespace: string (default: 'ui')
  keyPath: string (not null)
  category: string (not null)
  values: Record<string, string> (JSON)
  description: string (nullable)
  isOverrideable: boolean (default: true)
  createdAt: timestamp
  updatedAt: timestamp
}

unique(teamId, namespace, keyPath)

<script setup lang="ts">
const props = defineProps<{ action: 'create' | 'update', item?: Product }>()
const { create, update } = useCollectionMutation('products')

const state = ref({
  sku: props.item?.sku || '',
  name: props.item?.name || '',
  price: props.item?.price || 0,
  translations: props.item?.translations || {}
})

const handleSubmit = async () => {
  if (props.action === 'create') {
    await create(state.value)
  } else {
    await update(props.item!.id, state.value)
  }
}
</script>

<template>
  <UForm :state="state" @submit="handleSubmit">
    <UFormField label="SKU" name="sku" required>
      <UInput v-model="state.sku" />
    </UFormField>

    <UFormField label="Name (English)" name="name" required>
      <UInput v-model="state.name" />
    </UFormField>

    <CroutonButton :action="action" collection="products" />
  </UForm>
</template>

<template>
  <UForm :state="state" @submit="handleSubmit">
    <!-- Default language fields -->
    <UFormField label="Name (English)" name="name" required>
      <UInput v-model="state.name" />
    </UFormField>

    <UFormField label="Description (English)" name="description">
      <UTextarea v-model="state.description" rows="3" />
    </UFormField>

    <!-- Translations component -->
    <UFormField label="Translations">
      <CroutonI18nInput
        v-model="state.translations"
        :fields="['name', 'description']"
        :default-values="{ name: state.name, description: state.description }"
        :field-components="{ description: 'UTextarea' }"
      />
    </UFormField>

    <CroutonButton :action="action" collection="products" />
  </UForm>
</template>

<script setup lang="ts">
const { locale } = useI18n()
const { items } = await useCollectionQuery('products', {
  query: computed(() => ({
    locale: locale.value
  }))
})

const { t } = useEntityTranslations()
</script>

<template>
  <div class="grid gap-4">
    <div v-for="product in items" :key="product.id" class="card">
      <!-- Translated name -->
      <h3>{{ t(product, 'name') }}</h3>

      <!-- Translated description -->
      <p>{{ t(product, 'description') }}</p>

      <!-- Translation status badges -->
      <CroutonI18nListCards
        :item="product"
        :fields="['name', 'description']"
      />

      <!-- Non-translated fields -->
      <div class="text-sm text-gray-500">
        SKU: {{ product.sku }} | Price: {{ product.price }}
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
// Full admin page for UI translations
definePageMeta({
  middleware: 'admin'
})
</script>

<template>
  <div class="space-y-6">
    <div class="flex justify-between items-center">
      <h1>UI Translations</h1>
      <CroutonI18nLanguageSwitcher />
    </div>

    <!-- Translation management table -->
    <CroutonI18nUiList />

    <!-- Dev mode toggle for testing -->
    <CroutonI18nDevModeToggle />
  </div>
</template>

<!-- ✅ Good -->
<CroutonI18nInput
  v-model="state.translations"
  :fields="['name']"
  :default-values="{ name: state.name }"
/>

<!-- ❌ Bad - No English default -->
<CroutonI18nInput
  v-model="state.translations"
  :fields="['name']"
/>

// ✅ Good - Entity field translations
{
  id: '123',
  name: 'Product',
  translations: {
    nl: { name: 'Product' },
    fr: { name: 'Produit' }
  }
}

// ❌ Bad - Don't use UI translations for content
// UI translations are for interface labels only

// ✅ Good
'common.save'
'common.cancel'
'table.search'
'table.filter'
'dashboard.title'

// ❌ Bad
'save'
'cancelButton'
'SearchTable'

<script setup lang="ts">
// ✅ Good - Relies on automatic fallback
const { t } = useEntityTranslations()
const name = t(product, 'name')

// ❌ Bad - Manual fallback logic
const name = product.translations?.[locale.value]?.name || product.name || ''
</script>

<!-- ✅ Good - Rich text for long content -->
<CroutonI18nInput
  v-model="state.translations"
  :fields="['content']"
  :field-components="{ content: 'CroutonEditorSimple' }"
/>

<!-- ❌ Bad - Plain text for HTML content -->
<CroutonI18nInput
  v-model="state.translations"
  :fields="['content']"
/>

<template>
  <!-- ✅ Good - Always include in dev layout -->
  <CroutonI18nDevModeToggle />

  <!-- Quickly identify and fix missing translations -->
</template>

const { refreshTranslations } = useT()
await refreshTranslations()

<template>
  <CroutonI18nDevModeToggle />
  <!-- Click highlighted translations to add them -->
</template>

<script setup lang="ts">
const { locale } = useI18n()
console.log('Current locale:', locale.value)

// Ensure query includes locale
const { items } = await useCollectionQuery('products', {
  query: computed(() => ({ locale: locale.value }))
})
</script>