@ui18n/svelte/README.md

🧡 Lightning-fast Svelte internationalization with reactive stores, SvelteKit support, and zero-bundle overhead

# @ui18n/svelte

> 🌍 UI18n Svelte集成包 - 为Svelte应用提供智能国际化支持

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Svelte](https://img.shields.io/badge/Svelte-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev/)

## ✨ 特性

- **🎨 完全可定制**：组件UI完全可定制，不受任何限制
- **⚡ 响应式设计**：基于Svelte stores的响应式状态管理
- **🧠 智能翻译**：集成AI翻译，支持缓存和批量优化
- **🔄 实时切换**：语言切换即时生效，无需刷新页面
- **🌍 智能检测**：自动检测用户系统语言
- **📦 轻量高效**：零依赖核心，按需加载功能
- **🎯 TypeScript**：完整的类型支持和智能提示

## 🚀 快速开始

### 安装

```bash
npm install @ui18n/svelte @ui18n/core
```

### 基础使用

```svelte
<script>
  import { createUI18nStore, LanguageSelector, T } from '@ui18n/svelte';
  
  // 创建UI18n store
  const ui18nStore = createUI18nStore({
    defaultLanguage: 'zh-CN',
    aiProvider: {
      type: 'openai',
      apiKey: 'your-api-key'
    }
  });
</script>

<!-- 语言选择器 -->
<LanguageSelector {ui18nStore} />

<!-- 翻译组件 -->
<T {ui18nStore} text="欢迎使用UI18n" />

<!-- 手动翻译 -->
<p>{$ui18nStore.currentLanguage}</p>
```

### 使用全局Store

```svelte
<!-- App.svelte -->
<script>
  import { setGlobalUI18nStore, LanguageSelector } from '@ui18n/svelte';
  
  // 设置全局store
  const ui18nStore = setGlobalUI18nStore({
    defaultLanguage: 'zh-CN'
  });
</script>

<LanguageSelector {ui18nStore} />
```

```svelte
<!-- 其他组件中使用 -->
<script>
  import { getGlobalUI18nStore, t } from '@ui18n/svelte';
  
  const ui18nStore = getGlobalUI18nStore();
  
  // 使用便捷翻译函数
  let translatedText = '';
  t('Hello World').then(result => {
    translatedText = result;
  });
</script>

<p>{translatedText}</p>
```

## 📦 API文档

### Stores

#### `createUI18nStore(config)`

创建UI18n store实例。

```typescript
import { createUI18nStore } from '@ui18n/svelte';

const ui18nStore = createUI18nStore({
  defaultLanguage: 'zh-CN',
  aiProvider: {
    type: 'openai',
    apiKey: 'your-api-key'
  }
});

// 响应式状态
$: console.log($ui18nStore.currentLanguage);
$: console.log($ui18nStore.loading);
$: console.log($ui18nStore.error);
```

**返回值：**
- `subscribe`: Svelte store订阅函数
- `setLanguage(language)`: 切换语言
- `translate(text, options?)`: 翻译文本
- `getLanguageDisplayName(lang, displayLang?)`: 获取语言显示名称
- `detectAndSetSystemLanguage()`: 检测并设置系统语言
- `searchLanguages(query, availableLanguages)`: 搜索语言

#### 全局Store管理

```typescript
import { 
  setGlobalUI18nStore, 
  getGlobalUI18nStore, 
  t 
} from '@ui18n/svelte';

// 设置全局store
setGlobalUI18nStore({ defaultLanguage: 'zh-CN' });

// 获取全局store
const store = getGlobalUI18nStore();

// 便捷翻译函数
const result = await t('Hello', { context: 'greeting' });
```

### 组件

#### `<LanguageSelector>`

语言选择器组件，提供完整的语言切换功能。

```svelte
<LanguageSelector
  {ui18nStore}
  defaultLanguages={['zh-CN', 'en']}
  showSearchBox={true}
  autoDetectSystemLanguage={true}
  className="custom-selector"
  on:languageChange={handleLanguageChange}
/>
```

**Props：**
- `ui18nStore`: UI18n store实例（必需）
- `defaultLanguages`: 默认显示的语言列表
- `showSearchBox`: 是否显示搜索框
- `autoDetectSystemLanguage`: 是否自动检测系统语言
- `className`: 自定义CSS类名

**事件：**
- `languageChange`: 语言切换时触发

**插槽：**
```svelte
<LanguageSelector {ui18nStore}>
  <!-- 自定义语言按钮 -->
  <svelte:fragment slot="language-button" let:lang let:isActive let:onClick>
    <button class:active={isActive} on:click={onClick}>
      {lang}
    </button>
  </svelte:fragment>
  
  <!-- 自定义搜索框 -->
  <svelte:fragment slot="search-box" let:value let:onInput>
    <input {value} on:input={onInput} placeholder="搜索..." />
  </svelte:fragment>
  
  <!-- 自定义加载状态 -->
  <svelte:fragment slot="loading">
    <div class="spinner">加载中...</div>
  </svelte:fragment>
  
  <!-- 自定义错误状态 -->
  <svelte:fragment slot="error" let:error>
    <div class="error">错误: {error}</div>
  </svelte:fragment>
</LanguageSelector>
```

#### `<T>`

翻译组件，用于翻译单个文本。

```svelte
<T 
  {ui18nStore}
  text="Hello World"
  language="en"
  context="greeting"
  fallback="你好世界"
/>
```

**Props：**
- `ui18nStore`: UI18n store实例（必需）
- `text`: 需要翻译的文本（必需）
- `language`: 目标语言（可选）
- `context`: 翻译上下文（可选）
- `fallback`: 翻译失败时的备用文本

**插槽：**
```svelte
<T {ui18nStore} text="Hello" let:translatedText>
  <strong>{translatedText}</strong>
</T>

<!-- 自定义加载状态 -->
<T {ui18nStore} text="Hello">
  <svelte:fragment slot="loading">
    <span class="loading">翻译中...</span>
  </svelte:fragment>
</T>

<!-- 自定义错误状态 -->
<T {ui18nStore} text="Hello">
  <svelte:fragment slot="error" let:error>
    <span class="error" title={error}>翻译失败</span>
  </svelte:fragment>
</T>
```

## 🎨 自定义样式

### CSS变量

```css
.ui18n-language-selector {
  --ui18n-primary-color: #3b82f6;
  --ui18n-border-color: #e0e0e0;
  --ui18n-background-color: #fff;
  --ui18n-text-color: #333;
  --ui18n-border-radius: 8px;
  --ui18n-padding: 16px;
  --ui18n-gap: 12px;
}
```

### 完全自定义

```svelte
<script>
  import { createUI18nStore } from '@ui18n/svelte';
  
  const ui18nStore = createUI18nStore({
    defaultLanguage: 'zh-CN'
  });
  
  const languages = ['zh-CN', 'en', 'ja'];
  
  async function handleLanguageClick(lang) {
    await ui18nStore.setLanguage(lang);
  }
</script>

<!-- 完全自定义的语言选择器 -->
<div class="my-language-selector">
  {#each languages as lang}
    <button 
      class="lang-btn"
      class:active={$ui18nStore.currentLanguage === lang}
      on:click={() => handleLanguageClick(lang)}
      disabled={$ui18nStore.loading}
    >
      {ui18nStore.getLanguageDisplayName(lang)}
    </button>
  {/each}
</div>

<style>
  .my-language-selector {
    display: flex;
    gap: 8px;
  }
  
  .lang-btn {
    padding: 8px 16px;
    border: 1px solid #ccc;
    border-radius: 4px;
    background: white;
    cursor: pointer;
  }
  
  .lang-btn.active {
    background: #3b82f6;
    color: white;
  }
</style>
```

## 🔧 高级用法

### 响应式翻译

```svelte
<script>
  import { createUI18nStore } from '@ui18n/svelte';
  
  const ui18nStore = createUI18nStore({
    defaultLanguage: 'zh-CN'
  });
  
  let inputText = '你好';
  let translatedText = '';
  
  // 响应式翻译
  $: if (inputText) {
    ui18nStore.translate(inputText).then(result => {
      translatedText = result;
    });
  }
</script>

<input bind:value={inputText} placeholder="输入要翻译的文本" />
<p>翻译结果: {translatedText}</p>
```

### 批量翻译

```svelte
<script>
  import { createUI18nStore } from '@ui18n/svelte';
  
  const ui18nStore = createUI18nStore({
    defaultLanguage: 'zh-CN'
  });
  
  const texts = ['你好', '再见', '谢谢'];
  let translations = {};
  
  async function translateAll() {
    for (const text of texts) {
      translations[text] = await ui18nStore.translate(text);
    }
    translations = { ...translations }; // 触发响应式更新
  }
  
  translateAll();
</script>

{#each texts as text}
  <p>{text} → {translations[text] || '翻译中...'}</p>
{/each}
```

### 错误处理

```svelte
<script>
  import { createUI18nStore } from '@ui18n/svelte';
  
  const ui18nStore = createUI18nStore({
    defaultLanguage: 'zh-CN'
  });
  
  // 监听错误状态
  $: if ($ui18nStore.error) {
    console.error('UI18n错误:', $ui18nStore.error);
    // 显示错误提示或执行错误处理逻辑
  }
</script>

{#if $ui18nStore.error}
  <div class="error-banner">
    翻译服务出现问题: {$ui18nStore.error}
  </div>
{/if}
```

## 🌍 支持的语言

支持所有ISO 639-1标准语言代码，包括但不限于：

- `zh-CN` - 简体中文
- `zh-TW` - 繁体中文
- `en` - 英语
- `ja` - 日语
- `ko` - 韩语
- `fr` - 法语
- `de` - 德语
- `es` - 西班牙语
- `it` - 意大利语
- `pt` - 葡萄牙语
- `ru` - 俄语
- `ar` - 阿拉伯语

## 📄 许可证

MIT License - 详见 [LICENSE](../../LICENSE) 文件

## 🤝 贡献

欢迎提交Issue和Pull Request！

- [报告Bug](https://github.com/iron-wayne/UI18N-OSS/issues)
- [功能建议](https://github.com/iron-wayne/UI18N-OSS/discussions)
- [贡献指南](../../CONTRIBUTING.md)

---

<div align="center">

**如果这个项目对你有帮助，请给我们一个 ⭐ Star！**

[🌟 Star](https://github.com/iron-wayne/UI18N-OSS) | [🐛 Issues](https://github.com/iron-wayne/UI18N-OSS/issues) | [📚 文档](https://github.com/iron-wayne/UI18N-OSS#readme)

</div>