setupI18n

Configure internationalization (i18n) support for EletroDS components with multiple language support.

Overview

EletroDS provides built-in internationalization (i18n) support using Vue I18n. This allows you to translate component labels, messages, and other text content into multiple languages.

The i18n system is designed to work seamlessly with EletroDS components, especially those that require translated content like headers, error messages, and user-facing text.

Supported Locales

EletroDS supports the following locales out of the box:

• en-US - English (United States) - Default
• pt-BR - Portuguese (Brazil)
• es-ES - Spanish (Spain)
• es-MX - Spanish (Mexico)
• fr-CA - French (Canada)
• fr-FR - French (France)
• pt-PT - Portuguese (Portugal)

Installation

The i18n functionality is included in the @mercadoeletronico/eds-next package. No additional installation is required.

Setup

Nuxt.js Applications

For Nuxt.js applications, create a plugin file to initialize i18n:

import { setupI18n } from '@mercadoeletronico/eds-next'

export default defineNuxtPlugin(() => {
  // Initialize i18n with your desired locale
  setupI18n('pt-BR')
})

Vue.js Applications

For standard Vue.js applications, initialize i18n in your main entry file:

import { createApp } from 'vue'
import { setupI18n } from '@mercadoeletronico/eds-next'
import App from './App.vue'

// Initialize i18n before creating the app
setupI18n('pt-BR')

const app = createApp(App)
app.mount('#app')

Changing Locale at Runtime

You can change the locale dynamically by calling setupI18n again with a different locale:

import { setupI18n } from '@mercadoeletronico/eds-next'

// Change locale to Spanish
setupI18n('es-ES')

Usage

Using Translations in Components

Use the useI18n composable to access translation functions in your components:

<script setup lang="ts">
import { useI18n } from '@mercadoeletronico/eds-next'

const { t, locale } = useI18n()
</script>

<template>
  <div>
    <p>{{ t('header.tabs.loading') }}</p>
    <p>Current locale: {{ locale }}</p>
  </div>
</template>

Translation Keys

EletroDS uses a structured key system for translations. Here are some common translation keys:

Header Component Keys

// Tabs
t('header.tabs.othersFuncionality')
t('header.tabs.loading')
t('header.tabs.navigationItems.pinnedApps')
t('header.tabs.siteMapItems.search')

// API Errors
t('header.apiErrors.getTotalMessages')
t('header.apiErrors.generic')

Example: Using Translations in useHeader Composable

The useHeader composable automatically uses i18n for error messages:

import { useI18n } from '@mercadoeletronico/eds-next'

export function useHeader() {
  const { t } = useI18n()
  
  const showErrorToast = (messageKey: string = 'header.apiErrors.generic') => {
    showToastFn({ content: t(messageKey) })
  }
  
  // ... rest of the implementation
}

API Reference

setupI18n(locale?: SupportedLocale): I18n

Initializes or updates the i18n instance with a specific locale.

Parameters:

Returns: I18n - The Vue I18n instance

Example:

import { setupI18n } from '@mercadoeletronico/eds-next'

// Initialize with default locale (en-US)
setupI18n()

// Initialize with specific locale
setupI18n('pt-BR')

// Change locale at runtime
setupI18n('es-ES')

useI18n(): UseI18nReturn

Composable function that provides access to translation functions and locale.

Returns:

{
  t: Composer['t']        // Translation function
  locale: Composer['locale']  // Reactive locale reference
}

Example:

import { useI18n } from '@mercadoeletronico/eds-next'

const { t, locale } = useI18n()

// Use translation function
const loadingText = t('header.tabs.loading')

// Access current locale
console.log(locale.value) // 'pt-BR'

// Change locale
locale.value = 'es-ES'

messages

Exported messages object containing all locale translations.

import { messages } from '@mercadoeletronico/eds-next'

// Access messages for a specific locale
const ptBRMessages = messages['pt-BR']

SupportedLocale

Type definition for supported locales.

import type { SupportedLocale } from '@mercadoeletronico/eds-next'

const locale: SupportedLocale = 'pt-BR'

Type Definitions

SupportedLocale

type SupportedLocale = 
  | 'en-US' 
  | 'pt-BR' 
  | 'es-ES' 
  | 'es-MX' 
  | 'fr-CA' 
  | 'fr-FR' 
  | 'pt-PT'

Best Practices

1. Initialize Early

Always initialize i18n before using any EletroDS components that depend on translations:

// ✅ Good: Initialize in plugin
export default defineNuxtPlugin(() => {
  setupI18n('pt-BR')
})

// ❌ Bad: Initialize after component usage
const { t } = useI18n() // May fail if not initialized

2. Use Consistent Locale

Set the locale based on user preferences or application settings:

// Get locale from user settings or browser
const userLocale = getUserLocale() || 'pt-BR'
setupI18n(userLocale)

3. Handle Missing Translations

The i18n system will return the translation key if a translation is missing. Always ensure your translation keys exist:

// ✅ Good: Use existing keys
t('header.tabs.loading')

// ⚠️ Warning: Missing key will return the key itself
t('header.nonExistent.key') // Returns: 'header.nonExistent.key'

Troubleshooting

Translations Not Working

If translations are not appearing:

1. Verify initialization: Ensure setupI18n is called before using useI18n
2. Check locale: Verify the locale is set correctly and matches available locales
3. Verify keys: Ensure translation keys exist in the locale files

Locale Not Changing

If the locale is not updating:

1. Call setupI18n again: Use setupI18n(newLocale) to update the locale
2. Check reactivity: Ensure you're using the reactive locale ref from useI18n()

Exports

The following exports are available from @mercadoeletronico/eds-next:

• setupI18n - Function to initialize i18n instance
• useI18n - Composable to access translation functions
• messages - Object containing all locale translations
• SupportedLocale - Type definition for supported locales

Next Steps