SvelteKit i18n:国际化设置指南
从零到多语言:在 SvelteKit 应用中设置 svelte-i18n,使用 ICU 消息格式、基于语言的路由和智能回退链。
安装 svelte-i18n
svelte-i18n 是 Svelte 和 SvelteKit 的标准国际化库,开箱即用地提供响应式 store、ICU MessageFormat 支持和语言延迟加载。
npm install svelte-i18n配置 svelte-i18n
创建 i18n 配置文件,通过延迟加载的 import 函数注册语言。svelte-i18n 只会在某种语言启用时获取其消息。
// src/lib/i18n.ts
import { register, init, getLocaleFromNavigator } from 'svelte-i18n';
// Register locale loaders (lazy-loaded)
register('en', () => import('../locales/en.json'));
register('de', () => import('../locales/de.json'));
register('ja', () => import('../locales/ja.json'));
register('es', () => import('../locales/es.json'));
init({
fallbackLocale: 'en',
initialLocale: getLocaleFromNavigator(), // Auto-detect browser language
});SvelteKit 布局集成
在根布局中导入 i18n 配置,并通过 $isLoading store 控制渲染。这样可防止语言数据异步加载时短暂显示未翻译的键。
<!-- src/routes/+layout.svelte -->
<script>
// Import i18n config — must run before any component renders
import '../lib/i18n';
import { isLoading } from 'svelte-i18n';
</script>
{#if $isLoading}
<p>Loading translations...</p>
{:else}
<slot />
{/if}SvelteKit 中基于语言的路由
若要使用 /en/about、/de/about 等有利于 SEO 的 URL,请使用 [lang] 路由参数。根据 URL 参数,在布局的 load 函数中设置 svelte-i18n 语言。
// src/routes/[lang]/+layout.ts
import { locale } from 'svelte-i18n';
export function load({ params }) {
// Set the active locale from the URL parameter
locale.set(params.lang);
return {};
}
// src/routes/[lang]/+layout.svelte
<script>
import '../../lib/i18n';
import { isLoading } from 'svelte-i18n';
</script>
{#if $isLoading}
<p>Loading...</p>
{:else}
<slot />
{/if}翻译文件格式
为每种语言创建一个 JSON 文件。svelte-i18n 支持嵌套键,以及用于复数、变量和 select 表达式的 ICU MessageFormat 语法。
// src/locales/en.json
{
"nav": {
"home": "Home",
"about": "About",
"settings": "Settings"
},
"greeting": "Hello, {name}!",
"cart": {
"itemCount": "{count, plural, one {# item} other {# items}}"
}
}
// src/locales/de.json
{
"nav": {
"home": "Startseite",
"about": "Uber uns",
"settings": "Einstellungen"
},
"greeting": "Hallo, {name}!",
"cart": {
"itemCount": "{count, plural, one {# Artikel} other {# Artikel}}"
}
}在组件中使用译文
从 svelte-i18n 导入 $_ store(或 $format),并在 Svelte 模板中使用。store 具有响应性,语言变化时所有翻译字符串都会自动更新。
<script>
import { _ } from 'svelte-i18n';
</script>
<h1>{$_('greeting', { values: { name: 'World' } })}</h1>
<nav>
<a href="/">{$_('nav.home')}</a>
<a href="/about">{$_('nav.about')}</a>
</nav><script>
import { _, date, number, time } from 'svelte-i18n';
</script>
<!-- Simple string -->
<p>{$_('greeting', { values: { name: userName } })}</p>
<!-- ICU plurals — handled automatically -->
<p>{$_('cart.itemCount', { values: { count: 3 } })}</p>
<!-- Date formatting -->
<p>{$date(new Date(), { format: 'long' })}</p>
<!-- Number formatting -->
<p>{$number(1999.99, { style: 'currency', currency: 'USD' })}</p>语言切换
构建与 $locale store 绑定的语言选择器。值变化时,svelte-i18n 会加载新语言的消息,并以响应方式更新所有翻译字符串。
<script>
import { locale, locales } from 'svelte-i18n';
const LANGUAGE_NAMES = {
en: 'English',
de: 'Deutsch',
ja: '日本語',
es: 'Espanol',
};
</script>
<select bind:value={$locale}>
{#each $locales as loc}
<option value={loc}>{LANGUAGE_NAMES[loc] ?? loc}</option>
{/each}
</select>使用 ICU MessageFormat 处理复数
svelte-i18n 使用 ICU MessageFormat 处理复数,这是覆盖全部 CLDR 复数类别的国际标准。阿拉伯语有 6 种形式,俄语有 4 种,日语只有 1 种。定义目标语言需要的形式后,svelte-i18n 会自动选择正确形式。
// svelte-i18n uses ICU MessageFormat for plurals
// English:
{
"items": "{count, plural, one {# item} other {# items}}"
}
// Arabic (6 forms):
{
"items": "{count, plural, zero {no items} one {item} two {two items} few {# items} many {# items} other {# items}}"
}
// Japanese (1 form):
{
"items": "{count, plural, other {#個のアイテム}}"
}使用 svelte-i18n-locale-chain 实现智能语言回退
缺少键时,svelte-i18n 会直接回退到 fallbackLocale,没有中间回退。pt-BR 用户会看到英语,而不是完全可用的 pt-PT 译文。svelte-i18n-locale-chain 通过智能回退链深度合并区域变体消息,从而修复此问题。
npm install svelte-i18n-locale-chain svelte-i18n// src/lib/i18n.ts
import { initLocaleChain, setLocale } from 'svelte-i18n-locale-chain';
// Replace svelte-i18n's init + register with initLocaleChain
await initLocaleChain({
loadMessages: (locale) =>
import(`../locales/${locale}.json`).then(m => m.default),
defaultLocale: 'en',
initialLocale: 'pt-BR',
});
// Later, to change locale:
await setLocale('fr-CA');
// fr-CA user sees: fr-CA messages -> fr messages -> en messages
// No missing keys — deep-merged automatically自动翻译
完成 i18n 设置后,使用 AI 翻译本地化文件。在 IDE 中让 AI 助手翻译源文件,或在 CI/CD 管线中使用 i18n Agent CLI。
# In your IDE, ask your AI assistant:
> Translate src/locales/en.json to German, Japanese, and Spanish
✓ de.json created (1.2s)
✓ ja.json created (1.5s)
✓ es.json created (1.1s)
# Or use the CLI in CI/CD:
npx i18n-agent translate src/locales/en.json --lang de,ja,es自动保证翻译质量
常见问题
SvelteKit SSR 语言状态串扰
将 register() 与 svelte-i18n-locale-chain 一起使用
ICU 语法错误无提示失败
未翻译内容闪现
推荐的文件结构
my-sveltekit-app/
├── src/
│ ├── lib/
│ │ └── i18n.ts # i18n configuration
│ ├── locales/
│ │ ├── en.json # Source language
│ │ ├── de.json # German
│ │ ├── ja.json # Japanese
│ │ └── es.json # Spanish
│ └── routes/
│ ├── +layout.svelte # Import i18n, guard isLoading
│ ├── +page.svelte
│ └── [lang]/ # Optional: locale-based routing
│ ├── +layout.ts # Set locale from URL param
│ ├── +layout.svelte
│ └── +page.svelte
├── svelte.config.js
└── package.json立即试用 i18n Agent
将翻译文件拖放到此处
JSON, YAML, PO, XML, CSV, Markdown, Properties
或点击选择文件
目标语言
使用 svelte-i18n-locale-chain 实现语言回退
如果 pt-BR 等区域语言缺少翻译键,svelte-i18n 会直接跳到默认语言,而不会先检查父语言 pt。
npm install svelte-i18n-locale-chainimport { initLocaleChain } from 'svelte-i18n-locale-chain';
initLocaleChain({
fallbacks: {
'pt-BR': ['pt', 'en'],
'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
},
defaultLocale: 'en',
});查看语言回退指南,了解受支持框架的完整列表和 75 条内置回退链。 Learn more →