Svelte/SvelteKit 多语言配置指南

天渺工作室
11 阅读4分钟

方案对比

方案适用场景复杂度依赖大小
自定义 StoreSvelteKit 全栈低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>

对比：

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

5. SSR 服务端渲染支持

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

服务端与客户端的差异：

环境可用不可用
服务端URL、Cookie、HeaderlocalStorage、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()}

工作原理：

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

参考资源

avatar
文章
阅读
粉丝