# How to Add New Languages for i18n Support in Vue-Color-Avatar

> Easily add new languages for i18n support in Vue-Color-Avatar. Learn to extend the Locale enum and register new translation messages step by step.

- Repository: [LeoKu/vue-color-avatar](https://github.com/codennnn/vue-color-avatar)
- Tags: how-to-guide
- Published: 2026-02-27

---

**To add new languages for i18n support in vue-color-avatar, extend the `Locale` enum in [`src/enums/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/enums/index.ts), create a translation bundle in `src/i18n/locales/{lang}/index.ts`, and register the new messages in [`src/i18n/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/index.ts).**

The vue-color-avatar project uses **vue-i18n** to provide multilingual UI text for its avatar generator interface. If you want to add new languages for i18n support beyond the built-in English and Chinese, you must extend three core parts of the localization infrastructure: the locale enum, the message bundles, and the i18n instance configuration.

## Understanding the i18n Architecture

Before adding a language, understand how the project structures its internationalization:

- **[`src/enums/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/enums/index.ts)** – Defines the `Locale` enum that type-safely identifies supported languages (e.g., `Locale.EN`, `Locale.ZH`).
- **`src/i18n/locales/`** – Contains one folder per language (e.g., `en/`, `zh/`). Each folder exports an object with identical keys for UI text, labels, and actions.
- **[`src/i18n/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/index.ts)** – Bootstraps the vue-i18n plugin, imports all message bundles, and determines the active locale based on browser detection or fallback logic.

## Step 1: Extend the Locale Enum

Add your new language identifier to the `Locale` enum in [`src/enums/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/enums/index.ts). This ensures type safety throughout the application.

```typescript
// src/enums/index.ts
export const enum Locale {
  ZH = 'zh',
  EN = 'en',
  ES = 'es',   // ← Add new language code here
}

```

## Step 2: Create the Translation Bundle

Create a new directory for your language under `src/i18n/locales/` (e.g., `src/i18n/locales/es/`). Inside, create an [`index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/index.ts) file that exports an object matching the structure of existing bundles like `en` or `zh`.

The bundle must include keys for `action`, `label`, `widgetType`, `wrapperShape`, and `text`, using the `WidgetType` enum for widget keys.

```typescript
// src/i18n/locales/es/index.ts
import { WidgetType } from '@/enums'

export const es = {
  action: {
    undo: 'Deshacer',
    redo: 'Rehacer',
    flip: 'Voltear',
    code: 'Código',
    randomize: 'Aleatorio',
    download: 'Descargar',
    downloadMultiple: 'Generar varios',
    copyCode: 'Copiar',
    copied: 'Copiado',
    downloading: 'Descargando',
    close: 'Cerrar',
  },
  label: {
    wrapperShape: 'Forma del avatar',
    borderColor: 'Color del borde',
    backgroundColor: 'Color de fondo',
    colors: 'Colores',
  },
  widgetType: {
    [WidgetType.Face]: 'Cara',
    [WidgetType.Tops]: 'Cabello / Accesorios',
    [WidgetType.Ear]: 'Oreja',
    [WidgetType.Earrings]: 'Pendientes',
    [WidgetType.Eyebrows]: 'Cejas',
    [WidgetType.Eyes]: 'Ojos',
    [WidgetType.Nose]: 'Nariz',
    [WidgetType.Glasses]: 'Gafas',
    [WidgetType.Mouth]: 'Boca',
    [WidgetType.Beard]: 'Barba',
    [WidgetType.Clothes]: 'Ropa',
  },
  wrapperShape: {
    circle: 'Círculo',
    square: 'Cuadrado',
    squircle: 'Cuadrado redondeado',
  },
  text: {
    codeModalTitle: 'Código',
    downloadTip: 'Mantén pulsado o haz clic derecho para guardar',
    downloadMultiple: 'Descargar todo',
    downloadingMultiple: 'Descargando',
    downloadMultipleTip: 'Avatares generados automáticamente',
    regenerate: 'Regenerar',
  },
}

```

## Step 3: Register the New Language

Import your new bundle and add it to the `messages` object in [`src/i18n/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/index.ts). You can also extend the browser language detection logic if desired.

```typescript
// src/i18n/index.ts
import { createI18n } from 'vue-i18n'
import { Locale } from '@/enums'
import { en } from './locales/en'
import { zh } from './locales/zh'
import { es } from './locales/es'   // ← Import new language

const messages = { en, zh, es }      // ← Add to messages map

// Optional: Add detection for Spanish
const [locale, fallbackLocale] = /^zh\b/.test(window.navigator.language)
  ? [Locale.ZH, Locale.EN]
  : /^es\b/.test(window.navigator.language)
    ? [Locale.ES, Locale.EN]
    : [Locale.EN, Locale.ZH]

export const i18n = createI18n({
  locale,
  fallbackLocale,
  messages,
})

```

## Step 4: Update the UI Language Selector

The project includes a language selector in the configurator UI. Locate the component that renders language options (typically in the header or settings panel) and add the new `Locale.ES` option to the available choices so users can manually switch languages.

## Step 5: Verify Your Implementation

Start the development server and test the new translations:

```bash
pnpm dev

# or

npm run dev

```

Switch your browser language to the new locale or use the UI selector. Verify that all UI strings appear correctly and that fallback logic works if translations are missing.

## Summary

- **Extend the enum**: Add your language code to `Locale` in [`src/enums/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/enums/index.ts) to enable type-safe references throughout the app.
- **Create the bundle**: Mirror the structure of existing locales in `src/i18n/locales/{lang}/index.ts`, ensuring all `action`, `label`, `widgetType`, `wrapperShape`, and `text` keys are present.
- **Register the messages**: Import the new bundle into [`src/i18n/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/index.ts) and add it to the `messages` object passed to `createI18n()`.
- **Update the UI**: Add the new locale to the language selector component so users can switch manually.
- **Test thoroughly**: Run the dev server and verify translations render correctly across all avatar configuration options.

## Frequently Asked Questions

### What file structure should I follow when adding new languages for i18n support?

Create a new folder under `src/i18n/locales/` named with your language code (e.g., `es` for Spanish, `fr` for French). Inside that folder, create an [`index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/index.ts) file that exports an object containing `action`, `label`, `widgetType`, `wrapperShape`, and `text` keys, mirroring the structure found in [`src/i18n/locales/en/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/locales/en/index.ts).

### Do I need to modify the auto-detection logic in src/i18n/index.ts?

No, modifying the auto-detection logic is optional. The existing code uses a regex test against `window.navigator.language` to choose between Chinese and English defaults. If you want the app to automatically detect your new language, add a regex check (e.g., `/^es\b/.test(window.navigator.language)`) to the conditional chain. Otherwise, users can manually select the language via the UI selector.

### How do I ensure type safety when adding translations?

Always add your new language to the `Locale` enum in [`src/enums/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/enums/index.ts) first. This enum is used throughout the application to type-check locale references. When creating your message bundle, copy the structure from an existing locale (like `en` or `zh`) to ensure you include all required keys, preventing runtime missing-translation errors.

### Can I add regional variants like es-MX or pt-BR?

Yes, you can add regional variants by using the full locale code as the folder name (e.g., `src/i18n/locales/es-MX/` or `src/i18n/locales/pt-BR/`). Add the corresponding entry to the `Locale` enum (e.g., `ES_MX = 'es-MX'`), and import the bundle in [`src/i18n/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/i18n/index.ts). Note that you may need to adjust the auto-detection regex to handle the hyphenated format (e.g., `/^es\b/` will match `es-MX` due to the word boundary).