## 方案对比

| 方案 | 适用场景 | 复杂度 | 依赖大小 |
|------|----------|--------|----------|
| **自定义 Store** | SvelteKit 全栈 | 低 | 0 |
| **svelte-i18n** | 纯 Svelte 应用 | 低 | ~3KB |
| **typesafe-i18n** | 类型安全优先 | 中 | ~5KB |
| **paraglide-js** | 编译时优化 | 中 | ~2KB |

---

## 方案一：自定义 Store（推荐 SvelteKit）

最轻量的方案，无需额外依赖，代码完全可控。

**GitHub**: 无（纯手写）

### 1. 目录结构

```
src/lib/i18n/
├── translations.ts      # 翻译数据聚合
├── index.ts             # 导出接口
└── locales/
    ├── zh.ts            # 中文
    └── en.ts            # 英文
```

### 2. 翻译文件

```typescript
// src/lib/i18n/locales/zh.ts
export const zh = {
    nav: {
        home: '首页',
        about: '关于'
    },
    welcome: '欢迎'
};

// src/lib/i18n/locales/en.ts
export const en = {
    nav: {
        home: 'Home',
        about: 'About'
    },
    welcome: 'Welcome'
};
```

### 3. 核心实现

```typescript
// src/lib/i18n/translations.ts
import { zh } from './locales/zh';
import { en } from './locales/en';

export const translations = { zh, en };
export type Language = keyof typeof translations;
export type TranslationType = typeof zh;

// 检测浏览器语言
export function detectLang(): Language {
    if (typeof navigator === 'undefined') return 'zh';
    const lang = navigator.language.toLowerCase();
    return lang.startsWith('zh') ? 'zh' : 'en';
}

// 从 localStorage 读取
export function getStoredLang(): Language | null {
    if (typeof localStorage === 'undefined') return null;
    const stored = localStorage.getItem('lang');
    return stored === 'zh' || stored === 'en' ? stored : null;
}
```

```typescript
// src/lib/i18n/index.ts
import { writable, derived, get } from 'svelte/store';
import { translations, detectLang, getStoredLang, type Language } from './translations';

// 优先从 localStorage 读取，否则检测浏览器语言
const initialLang = getStoredLang() || detectLang();

// 当前语言 Store
export const currentLang = writable<Language>(initialLang);

// 翻译函数 Store
export const t = derived(currentLang, ($lang) => {
    return (key: string): string => {
        const keys = key.split('.');
        let value: any = translations[$lang];
        for (const k of keys) {
            value = value?.[k];
        }
        // 回退到 key 本身
        return typeof value === 'string' ? value : key;
    };
});

// 切换语言
export function setLang(lang: Language) {
    currentLang.set(lang);
    if (typeof localStorage !== 'undefined') {
        localStorage.setItem('lang', lang);
    }
}

// 获取当前语言（非响应式，用于脚本）
export function getLang(): Language {
    return get(currentLang);
}
```

### 4. 组件中使用

**`$` 前缀的作用**：Svelte 中 `$storeName` 是 `storeName.subscribe()` 的语法糖，表示**自动订阅**该 Store，值变化时组件自动更新。

```html

<script lang="ts">
    import { currentLang, t, setLang } from '$lib/i18n';
    
    // 不带 $：获取 Store 对象本身
    console.log(currentLang);  // Store 对象 { subscribe, set, update }
    
    // 带 $：获取 Store 的当前值（自动订阅）
    console.log($currentLang); // 'zh' 或 'en'
</script>

<nav>
    
    <a href="/">{$t('nav.home')}</a>
    <a href="/about">{$t('nav.about')}</a>
    
    <button on:click={() => setLang($currentLang === 'zh' ? 'en' : 'zh')}>
        {$currentLang === 'zh' ? 'EN' : '中文'}
    </button>
</nav>
```

**对比**：

| 写法 | 含义 | 使用场景 |
|------|------|----------|
| `currentLang` | Store 对象 | 传递给函数、调用方法 |
| `$currentLang` | Store 的值 | 模板中显示、读取当前值 |

### 5. SSR 服务端渲染支持

SvelteKit 原生支持 SSR，语言从 URL/Cookie 检测，服务端预加载翻译。

**服务端与客户端的差异**：

| 环境 | 可用 | 不可用 |
|------|------|--------|
| 服务端 | URL、Cookie、Header | localStorage、navigator |
| 客户端 | 全部 | — |

**Cookie 工具函数**：

```typescript
// src/lib/i18n/cookies.ts
import type { Cookies } from '@sveltejs/kit';

export function getLangFromCookies(cookies: Cookies): 'zh' | 'en' {
    const stored = cookies.get('lang');
    return stored === 'zh' || stored === 'en' ? stored : 'zh';
}

export function setLangCookie(cookies: Cookies, lang: 'zh' | 'en') {
    cookies.set('lang', lang, {
        path: '/',
        maxAge: 60 * 60 * 24 * 365  // 1年
    });
}
```

**Layout Load**（服务端预加载）：

```typescript
// src/routes/+layout.ts
import type { LayoutLoad } from './$types';
import { translations } from '$lib/i18n/translations';
import { getLangFromCookies, setLangCookie } from '$lib/i18n/cookies';

export const load: LayoutLoad = ({ cookies, url }) => {
    // 服务端：从 Cookie 或 URL 参数获取语言
    const langParam = url.searchParams.get('lang');
    const lang = (langParam === 'en' ? 'en' : 'zh');

    // 同步 Cookie
    setLangCookie(cookies, lang);

    // 预加载翻译数据
    const t = translations[lang];

    return { lang, t };
};
```

**Layout**（接管切换）：

```html

<script lang="ts">
    import { onMount } from 'svelte';
    import { setLang } from '$lib/i18n';

    let { data, children } = $props();
    
    // 初始化语言
    setLang(data.lang);
    
    // 语言切换
    function switchLang() {
        const newLang = $currentLang === 'zh' ? 'en' : 'zh';
        setLang(newLang);
        // 跳转刷新
        window.location.href = `/?lang=${newLang}`;
    }
</script>

<nav>
    <a href="/?lang=zh">中文</a>
    <a href="/?lang=en">EN</a>
    <button on:click={switchLang}>
        当前: {$currentLang}
    </button>
</nav>

{@render children()}
```

**工作原理**：

1. 用户访问 `/?lang=en`
2. 服务端从 URL 读取参数，同步到 Cookie，返回预加载了英文的 HTML
3. 客户端 `setLang(data.lang)` 同步 Store，页面已有翻译
4. 用户切换语言 → 跳转 `/?lang=zh` → 服务端返回中文 HTML

**SEO 友好**：
- 搜索引擎爬虫访问 `/?lang=zh` 抓中文内容
- 访问 `/?lang=en` 抓英文内容
- 每个语言都有独立 URL

### 5. SSR 注意事项

```html

<script lang="ts">
    import { onMount } from 'svelte';
    import { setLang } from '$lib/i18n';
    
    onMount(() => {
        // 客户端才执行
        const saved = localStorage.getItem('lang');
        if (saved) setLang(saved as 'zh' | 'en');
    });
</script>
```

---

## 方案二：svelte-i18n （纯svelte推荐）

社区最流行的方案，API 设计简洁。

- **GitHub**: https://github.com/kaisermann/svelte-i18n
- **NPM**: https://www.npmjs.com/package/svelte-i18n

```bash
npm install svelte-i18n
```

### 初始化文件

```typescript
// src/lib/i18n.ts
import { register, init, getLocaleFromNavigator, locale } from 'svelte-i18n';

// 注册语言文件（懒加载）
register('zh', () => import('./locales/zh.json'));
register('en', () => import('./locales/en.json'));

// 初始化配置
init({
    fallbackLocale: 'zh',
    initialLocale: getLocaleFromNavigator()
});

// 导出切换函数
export { locale };
export const setLocale = (lang: string) => locale.set(lang);
```

### 应用入口引入

```typescript
// src/main.ts (纯 Svelte)
import './lib/i18n';  // ← 必须先导入初始化
import App from './App.svelte';

const app = new App({ target: document.body });
export default app;
```

```typescript
// src/routes/+layout.ts (SvelteKit)
import { browser } from '$app/environment';
import { locale, waitLocale } from 'svelte-i18n';
import '$lib/i18n';  // 导入执行初始化
import type { LayoutLoad } from './$types';

export const load: LayoutLoad = async () => {
    if (browser) {
        const saved = localStorage.getItem('lang');
        if (saved) locale.set(saved);
    }
    await waitLocale();  // 等待翻译加载完成
    return {};
};
```

### 组件使用

```html
<script>
    import { _, locale } from 'svelte-i18n';
    import { setLocale } from '$lib/i18n';
</script>

<h1>{$_('welcome')}</h1>
<p>{$_('footer.copyright')}</p>

<button on:click={() => setLocale($locale === 'zh' ? 'en' : 'zh')}>
    切换
</button>
```

### 带参数的翻译

```json
{
    "hello": "Hello {name}!",
    "items": "You have {count} item | You have {count} items"
}
```

```svelte
<p>{$_('hello', { values: { name: 'World' } })}</p>
<p>{$_('items', { values: { count: 5 } })}</p>
```

---

## 方案三：typesafe-i18n

类型安全的国际化方案，IDE 自动补全翻译 key。

- **GitHub**: https://github.com/ivanhofer/typesafe-i18n
- **文档**: https://typesafe-i18n.dev/

```bash
npm install typesafe-i18n
npx typesafe-i18n --setup  # 生成配置文件
```

### 自动生成类型

```typescript
// src/i18n/i18n-types.ts（自动生成）
export type Translation = {
    nav: {
        home: string;
        about: string;
    };
    welcome: string;
};
```

### 使用

```html
<script lang="ts">
    import { LL } from '$lib/i18n/i18n-svelte';
    import { setLocale } from '$lib/i18n/i18n-util';
</script>

<h1>{$LL.welcome()}</h1>
<a href="/about">{$LL.nav.about()}</a>
```

---

## 方案四：paraglide-js

编译时优化的国际化方案，零运行时开销。

- **GitHub**: https://github.com/opral/inlang-sdk
- **文档**: https://inlang.com/m/gerre34r/library-inlang-paraglideJs

```bash
npm install @inlang/paraglide-js
```

### 特点

- 编译时将翻译内联到代码中
- 只打包用到的翻译
- 支持 Tree Shaking

```typescript
// 编译后直接使用
import * as m from '$lib/paraglide/messages.js';

console.log(m.hello_world()); // "Hello World!"
```

---

## 方案五：URL 路由级多语言（SvelteKit）

SEO 友好的方案，语言体现在 URL 中。

```
/zh/about    → 中文关于页
/en/about    → 英文关于页
/about       → 默认语言
```

### 路由配置

```typescript
// src/params/lang.ts
import type { ParamMatcher } from '@sveltejs/kit';

export const match: ParamMatcher = (param) => {
    return ['zh', 'en'].includes(param);
};
```

```
src/routes/
├── [[lang=lang]]/         # 可选语言前缀
│   ├── +page.svelte
│   └── about/
│       └── +page.svelte
└── +layout.ts
```

### 加载翻译

```typescript
// src/routes/[[lang=lang]]/+layout.ts
import type { LayoutLoad } from './$types';
import { translations } from '$lib/i18n/translations';

export const load: LayoutLoad = ({ params }) => {
    const lang = (params.lang as 'zh' | 'en') || 'zh';
    return {
        lang,
        t: translations[lang]
    };
};
```

---

## 关键决策点

| 场景 | 推荐方案 | 理由 |
|------|----------|------|
| 快速上线 | svelte-i18n | 生态成熟，文档丰富 |
| 类型安全 | typesafe-i18n | 编译时检查，IDE 提示 |
| SEO 优先 | URL 路由级 | 语言在 URL，搜索引擎友好 |
| 极简依赖 | 自定义 Store | 零依赖，完全可控 |
| 大型应用 | paraglide-js | 编译优化，性能最好 |
| SSR + SEO | 自定义 Store + Cookie | 服务端预加载，客户端接管切换 |

---

## 最佳实践

### 1. 延迟加载翻译

```typescript
// 不要：import zh from './locales/zh';  // 打包进主 bundle
// 要：
register('zh', () => import('./locales/zh.json'));  // 按需加载
```

### 2. SSR 安全访问浏览器 API

```html
<script>
    import { browser } from '$app/environment';
    import { onMount } from 'svelte';
    
    // 方式一：onMount
    onMount(() => {
        localStorage.getItem('lang');  // 安全
    });
    
    // 方式二：browser 判断
    if (browser) {
        localStorage.getItem('lang');  // 安全
    }
</script>
```

### 3. 回退机制

```typescript
// 找不到翻译时回退到 key
export function t(key: string): string {
    const value = getNestedValue(translations[lang], key);
    return value || key;  // 回退到 key
}
```

### 4. 类型安全（自定义 Store 版）

```typescript
// 生成翻译 key 的类型
type DotPrefix<T extends string> = T extends '' ? '' : `.${T}`;

type DotPath<T> = (
    T extends object ?
        { [K in keyof T]:
            `${Exclude<K, symbol>}${DotPrefix<DotPath<T[K]>>}`
        }[keyof T] :
        ''
) extends infer D ? Extract<D, string> : never;

export type TranslationKey = DotPath<typeof zh>;

// 使用
export const t = (key: TranslationKey) => ...
// IDE 提示: 'nav.home' | 'nav.about' | 'welcome' ...
```

### 5. 语言切换动画

```html
{#key $currentLang}
    <div in:fade={{ duration: 150 }}>
        <h1>{$t('welcome')}</h1>
    </div>
{/key}
```

---

## 参考资源

- **Svelte 官方**: https://svelte.dev/
- **SvelteKit 官方**: https://kit.svelte.dev/
- **svelte-i18n**: https://github.com/kaisermann/svelte-i18n
- **typesafe-i18n**: https://typesafe-i18n.dev/
- **paraglide-js**: https://inlang.com/m/gerre34r/library-inlang-paraglideJs

$ 前缀的作用：Svelte 中 $storeName 是 storeName.subscribe() 的语法糖，表示自动订阅该 Store，值变化时组件自动更新。

Svelte/SvelteKit 多语言配置指南

Svelte/SvelteKit 多语言配置指南。

编程语言

Svelte国际化方案对比：自定义Store轻量无依赖，svelte-i18n社区流行，typesafe-i18n类型安全，paraglide-js编译优化。推荐SvelteKit项目使用自定义Store方案，支持SSR和SEO，实现多语言切换与URL同步。

TypeScript

路由

GitHub

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Svelte/SvelteKit 多语言配置指南-腾讯云开发者社区-腾讯云

Svelte/SvelteKit 多语言配置指南

Svelte/SvelteKit 多语言配置指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐