Internationalization (i18n)

Overview

@bdky/aaas-pilot-kit supports internationalization (i18n) starting from v1.1.2, implemented based on ICU MessageFormat standard, with built-in support for Chinese, English, Japanese, Korean 4 languages.

v1.1.2+ Unified Configuration

Starting from v1.1.2, locale becomes the unified entry for language configuration, controlling both:

• SDK UI interface text language
• ASR speech recognition and TTS speech synthesis language

Just set locale, no need to configure lang separately.

Core Features

• ICU MessageFormat Standard: Implemented using @messageformat/core, supports advanced formatting for plurals, genders, dates, etc.
• Source-as-Key Pattern: Chinese as key, better code readability
• Compilation Cache Optimization: Automatically caches compilation results, avoiding repeated compilation
• Custom Language Packs: Supports overriding built-in translations or adding new languages
• Dynamic Switching: Runtime language switching, takes effect immediately
• Unified Language Configuration: locale controls both UI and voice service language simultaneously

---

Quick Start

1. Set Language at Initialization (Simplest Configuration)

Just set locale, both interface and voice services will use the same language:

import {createAaaSPilotKit} from '@bdky/aaas-pilot-kit';

const kit = createAaaSPilotKit({
    // ... other configurations
    locale: 'en', // Both interface and voice use English
});

2. Use Language Enum (Recommended)

Language enum can be used for locale, providing better code hints:

import {createAaaSPilotKit, Language} from '@bdky/aaas-pilot-kit';

const kit = createAaaSPilotKit({
    // ... other configurations
    locale: Language.ENGLISH, // Equivalent to 'en'
});

3. Interface and Voice Use Different Languages

When interface and voice services need to use different languages, can override through asr.config.lang:

const kit = createAaaSPilotKit({
    locale: 'zh',  // Interface uses Chinese
    asr: {
        provider: 'baidu',
        config: {
            lang: 'en'  // Voice service uses English
        }
    }
});

4. Runtime Language Switching

// Switch to Japanese
kit.setLocale('ja');

// Get current language
const currentLocale = kit.getLocale(); // 'ja'

// Supports chain calls
kit.setLocale('ko').start();

---

Supported Languages

Interface Languages (i18n Built-in)

Language Code	Language Name	Status
zh	Chinese (Simplified)	Built-in (default)
en	English	Built-in
ja	日本語	Built-in
ko	한국어	Built-in
Custom	Any language	Through messages parameter

Voice Service Languages (ASR/TTS)

Code	Language	Language Enum
zh	Chinese (Mandarin)	Language.CHINESE
en	English	Language.ENGLISH
ja	Japanese	Language.JAPANESE
ko	Korean	Language.KOREAN
es	Spanish	Language.SPANISH
ru	Russian	Language.RUSSIAN
vi	Vietnamese	Language.VIETNAMESE
de	German	Language.GERMAN
id	Indonesian	Language.INDONESIAN
th	Thai	Language.THAI

---

API Reference

Initialization Configuration

locale

Type: 'zh' | 'en' | 'ja' | 'ko' | string Default Value: 'zh' Description: Set SDK interface language

createAaaSPilotKit({
    locale: 'en', // Use built-in English
});

messages

Type: Partial<I18nMessages> Description: Customize/override translation messages

Lookup Priority:

1. Custom messages
2. Built-in language pack for current locale
3. Chinese fallback (zh)
4. Key itself (original Chinese text)

createAaaSPilotKit({
    locale: 'en',
    messages: {
        // Override built-in translation
        '网络连接错误': 'Custom network error message',
    },
});

---

Runtime API

setLocale(locale: string)

Description: Dynamically switch SDK interface language Return Value: IAaaSPilotKitController (supports chain calls) Effective Timing: Immediate, affects all components using i18n

// Switch to English
kit.setLocale('en');

// Chain call
kit.setLocale('ja').start();

getLocale()

Description: Get current SDK interface language Return Value: string (current language code)

const currentLocale = kit.getLocale(); // 'zh'

---

Use Cases

Scenario 1: Auto-adapt based on browser language

// Get browser language
const browserLang = navigator.language.split('-')[0]; // 'en', 'zh', 'ja', 'ko'

const kit = createAaaSPilotKit({
    locale: ['zh', 'en', 'ja', 'ko'].includes(browserLang) ? browserLang : 'zh',
});

Scenario 2: User manually switches language

// React example
function LanguageSwitcher() {
    const kit = useAaaSPilotKit();

    const handleLanguageChange = (lang: string) => {
        kit.setLocale(lang);
    };

    return (
        <select onChange={(e) => handleLanguageChange(e.target.value)}>
            <option value="zh">中文</option>
            <option value="en">English</option>
            <option value="ja">日本語</option>
            <option value="ko">한국어</option>
        </select>
    );
}

Scenario 3: Add custom language (French example)

import {zhMessages} from '@bdky/aaas-pilot-kit';

// Translate all keys based on Chinese language pack
const frMessages = {
    '发生未知错误': 'Une erreur inconnue s\'est produite',
    '网络连接错误': 'Erreur de connexion réseau',
    '请求超时': 'Délai d\'attente de la requête',
    // ... translate all keys
};

const kit = createAaaSPilotKit({
    locale: 'fr',
    messages: frMessages,
});

Scenario 4: Override partial built-in translations

const kit = createAaaSPilotKit({
    locale: 'en',
    messages: {
        // Only override messages needing customization
        'ASR权限被拒绝': 'Microphone access denied. Please enable it in browser settings.',
    },
});

---

Exported Language Packs

SDK exports all built-in language packs for external translation reference:

import {
    zhMessages, // Chinese language pack
    enMessages, // English language pack
    jaMessages, // Japanese language pack
    koMessages, // Korean language pack
} from '@bdky/aaas-pilot-kit';

// View all translatable keys
console.log(Object.keys(zhMessages));

---

Advanced Features

ICU MessageFormat Interpolation

SDK supports ICU MessageFormat standard parameter interpolation:

// Built-in example (Chinese)
'请求超时，已重试 {count} 次'

// English translation
'Request timeout, retried {count} times'

// SDK internal usage
i18n.t('请求超时，已重试 {count} 次', {count: 3});
// Output: "请求超时，已重试 3 次"

Compilation Cache

SDK automatically caches compilation results, avoiding repeated compilation:

• Cache key: ${locale}:${messageKey}
• Automatically clears cache when switching languages
• Automatically clears cache when setting custom messages

---

Important Notes

1. t() method not exposed externally t() method is only for SDK internal use, external calls are not directly available. SDK will automatically translate all internal messages based on current locale.

2. Language switching takes effect immediately After calling setLocale(), all components using i18n will immediately use the new language.

3. Custom language packs need complete translation If adding a new language, it's recommended to translate all keys based on zhMessages, otherwise untranslated messages will fallback to Chinese.

4. ICU format errors will fallback If message template contains invalid ICU format, SDK will automatically fallback to simple interpolation ({key} replacement).

locale Unified Configuration (v1.1.2+)

Starting from v1.1.2, locale becomes the unified entry, controlling both interface language and voice service language simultaneously.

If interface and voice need to use different languages, can override voice service language through asr.config.lang.

---

Migration Guide

Migrate from lang to locale

// ❌ Old approach (deprecated)
const kit = createAaaSPilotKit({
    lang: 'en',
});

// ✅ New approach
const kit = createAaaSPilotKit({
    locale: 'en',
});

Migrate from lang to asr.config.lang

If only need to set voice service language without affecting interface:

// ❌ Old approach (deprecated)
const kit = createAaaSPilotKit({
    lang: 'en',
});

// ✅ New approach (voice service only)
const kit = createAaaSPilotKit({
    locale: 'zh',  // Keep interface in Chinese
    asr: {
        provider: 'baidu',
        config: { lang: 'en' }
    }
});

---

Priority Rules

The final value of voice service language follows the following priority:

1. asr.config.lang (if configured)
2. Automatically derived from locale
3. Default 'zh'

asr.config.lang > locale → automatically derived > default 'zh'

---

Edge Cases

Using non-built-in i18n language

When locale is set to a language supported by voice service but not built into i18n:

const kit = createAaaSPilotKit({
    locale: Language.SPANISH, // 'es'
});

Behavior:

• Interface language: Fallback to Chinese (i18n doesn't have built-in Spanish)
• Voice service: Normal use of Spanish

Solution: Provide custom language pack through messages parameter:

const kit = createAaaSPilotKit({
    locale: 'es',
    messages: {
        '发生未知错误': 'Error desconocido',
        '网络连接错误': 'Error de conexión de red',
        // ... other translations
    }
});

---

Complete Example

import {createAaaSPilotKit, zhMessages} from '@bdky/aaas-pilot-kit';

// 1. Initialize based on browser language
const browserLang = navigator.language.split('-')[0];
const supportedLangs = ['zh', 'en', 'ja', 'ko'];
const initialLocale = supportedLangs.includes(browserLang) ? browserLang : 'zh';

// 2. Create Kit instance
const kit = createAaaSPilotKit({
    // ... other configurations
    locale: initialLocale,
    messages: {
        // Optional: Override partial translations
        'ASR权限被拒绝': 'Custom permission denied message',
    },
});

// 3. Runtime language switching
document.getElementById('lang-zh')?.addEventListener('click', () => {
    kit.setLocale('zh');
});

document.getElementById('lang-en')?.addEventListener('click', () => {
    kit.setLocale('en');
});

// 4. Get current language
console.log('Current locale:', kit.getLocale());

---

Related Links

• ICU MessageFormat Syntax
• @messageformat/core Documentation