方案对比
| 方案 | 适用场景 | 复杂度 | 依赖大小 |
|---|
| 自定义 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. 翻译文件
// 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. 核心实现
// 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;
}
// 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，值变化时组件自动更新。
<!-- +layout.svelte -->
<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>
<!-- 使用 $t() 获取翻译，$currentLang 获取当前语言 -->
<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 工具函数：
// 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（服务端预加载）：
// 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（接管切换）：
<!-- src/routes/+layout.svelte -->
<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()}
工作原理：
- 用户访问
/?lang=en - 服务端从 URL 读取参数，同步到 Cookie，返回预加载了英文的 HTML
- 客户端
setLang(data.lang) 同步 Store，页面已有翻译 - 用户切换语言 → 跳转
/?lang=zh → 服务端返回中文 HTML
SEO 友好：
- 搜索引擎爬虫访问
/?lang=zh 抓中文内容 - 访问
/?lang=en 抓英文内容 - 每个语言都有独立 URL
5. SSR 注意事项
<!-- 安全访问 localStorage -->
<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 设计简洁。
npm install svelte-i18n
初始化文件
// 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);
应用入口引入
// src/main.ts (纯 Svelte)
import './lib/i18n'; // ← 必须先导入初始化
import App from './App.svelte';
const app = new App({ target: document.body });
export default app;
// 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 {};
};
组件使用
<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>
带参数的翻译
{
"hello": "Hello {name}!",
"items": "You have {count} item | You have {count} items"
}
<p>{$_('hello', { values: { name: 'World' } })}</p>
<p>{$_('items', { values: { count: 5 } })}</p>
方案三：typesafe-i18n
类型安全的国际化方案，IDE 自动补全翻译 key。
npm install typesafe-i18n
npx typesafe-i18n --setup # 生成配置文件
自动生成类型
// src/i18n/i18n-types.ts（自动生成）
export type Translation = {
nav: {
home: string;
about: string;
};
welcome: string;
};
使用
<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
编译时优化的国际化方案，零运行时开销。
npm install @inlang/paraglide-js
特点
- 编译时将翻译内联到代码中
- 只打包用到的翻译
- 支持 Tree Shaking
// 编译后直接使用
import * as m from '$lib/paraglide/messages.js';
console.log(m.hello_world()); // "Hello World!"
方案五：URL 路由级多语言（SvelteKit）
SEO 友好的方案，语言体现在 URL 中。
/zh/about → 中文关于页
/en/about → 英文关于页
/about → 默认语言
路由配置
// 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
加载翻译
// 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. 延迟加载翻译
// 不要：import zh from './locales/zh'; // 打包进主 bundle
// 要：
register('zh', () => import('./locales/zh.json')); // 按需加载
2. SSR 安全访问浏览器 API
<script>
import { browser } from '$app/environment';
import { onMount } from 'svelte';
// 方式一：onMount
onMount(() => {
localStorage.getItem('lang'); // 安全
});
// 方式二：browser 判断
if (browser) {
localStorage.getItem('lang'); // 安全
}
</script>
3. 回退机制
// 找不到翻译时回退到 key
export function t(key: string): string {
const value = getNestedValue(translations[lang], key);
return value || key; // 回退到 key
}
4. 类型安全（自定义 Store 版）
// 生成翻译 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. 语言切换动画
{#key $currentLang}
<div in:fade={{ duration: 150 }}>
<h1>{$t('welcome')}</h1>
</div>
{/key}
参考资源
