@ui18n/svelte

v0.1.0-rc.4

Published

9 months ago

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

@ui18n/svelte

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

✨ 特性

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

🚀 快速开始

安装

npm install @ui18n/svelte @ui18n/core

基础使用

<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

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

<LanguageSelector {ui18nStore} />

<!-- 其他组件中使用 -->
<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实例。

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管理

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

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

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

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

组件

`<LanguageSelector>`

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

<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: 语言切换时触发

插槽：

<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>`

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

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

Props：

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

插槽：

<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变量

.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;
}

完全自定义

<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>

🔧 高级用法

响应式翻译

<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>

批量翻译

<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}

错误处理

<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 文件

🤝 贡献

欢迎提交Issue和Pull Request！

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

🌟 Star | 🐛 Issues | 📚 文档

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ui18n/svelte

✨ 特性

🚀 快速开始

安装

基础使用

使用全局Store

📦 API文档

Stores

createUI18nStore(config)

全局Store管理

组件

<LanguageSelector>

<T>

🎨 自定义样式

CSS变量

完全自定义

🔧 高级用法

响应式翻译

批量翻译

错误处理

🌍 支持的语言

📄 许可证

🤝 贡献

`createUI18nStore(config)`

`<LanguageSelector>`

`<T>`