@vben_cimom/locales

A powerful internationalization (i18n) utility for Vue applications, providing easy-to-use multilingual support.

Installation

npm install @vben_cimom/locales
# or
yarn add @vben_cimom/locales
# or
pnpm add @vben_cimom/locales

Dependencies

This package requires the following peer dependencies:

npm install vue vue-i18n

Features

• Simple setup for Vue 3 applications
• Support for multiple languages (en-US, zh-CN by default)
• Dynamic loading of language files
• TypeScript support
• Automatic language detection and switching
• Custom message loading

Usage

Basic Setup

import { createApp } from 'vue';
import App from './App.vue';
import { setupI18n } from '@vben_cimom/locales';

const app = createApp(App);

// Setup i18n with default locale (zh-CN)
await setupI18n(app);

app.mount('#app');

Custom Setup

import { createApp } from 'vue';
import App from './App.vue';
import { setupI18n } from '@vben_cimom/locales';

const app = createApp(App);

// Setup i18n with custom options
await setupI18n(app, {
  defaultLocale: 'en-US',
  loadMessages: async (lang) => {
    // Load custom messages
    return {
      custom: {
        hello: lang === 'en-US' ? 'Hello' : '你好',
      },
    };
  },
  missingWarn: true,
});

app.mount('#app');

Switching Languages

import { loadLocaleMessages } from '@vben_cimom/locales';

// Switch to English
await loadLocaleMessages('en-US');

// Switch to Chinese
await loadLocaleMessages('zh-CN');

Using in Components

<template>
  <div>
    <h1>{{ $t('common.title') }}</h1>
    <button @click="switchLanguage">
      {{ $t('common.switchLanguage') }}
    </button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { loadLocaleMessages, type SupportedLanguagesType } from '@vben_cimom/locales';

const currentLocale = ref('zh-CN');

const switchLanguage = async () => {
  const newLocale = currentLocale.value === 'zh-CN' ? 'en-US' : 'zh-CN';
  await loadLocaleMessages(newLocale);
  currentLocale.value = newLocale;
};
</script>

Using Composition API

<template>
  <div>
    <h1>{{ t('common.title') }}</h1>
    <p>{{ t('common.description') }}</p>
  </div>
</template>

<script setup>
import { useI18n } from '@vben_cimom/locales';

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

API

setupI18n

Sets up the i18n instance for your Vue application.

function setupI18n(app: App, options?: LocaleSetupOptions): Promise<void>

Options

interface LocaleSetupOptions {
  defaultLocale?: 'en-US' | 'zh-CN';
  loadMessages?: (lang: string) => Promise<Record<string, any> | undefined>;
  missingWarn?: boolean;
}

loadLocaleMessages

Loads locale messages for a specific language.

function loadLocaleMessages(lang: 'en-US' | 'zh-CN'): Promise<void>

i18n

The Vue I18n instance.

const i18n: I18n

$t and $te

Global translation functions.

const $t: TranslateFunction
const $te: ExistFunction

Adding Custom Languages

To add custom languages, you can create a directory structure like this:

src/
  langs/
    custom-lang/
      common.json
      other-category.json

Then load them using the loadMessages option:

await setupI18n(app, {
  loadMessages: async (lang) => {
    if (lang === 'custom-lang') {
      return {
        common: { /* translations */ },
        otherCategory: { /* translations */ }
      };
    }
    return {};
  }
});

Browser Compatibility

This package is compatible with all modern browsers that support Vue 3. For older browsers, you may need to use appropriate polyfills.

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

License

MIT