使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
版本历史
- "更新 Solid useIntlayer API 用法以直接访问属性"v8.9.02026/5/4
- "添加 init 命令"v7.5.92025/12/30
- "初始化历史记录"v7.1.102025/11/20
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
使用 Intlayer 翻译您的 SvelteKit 网站 | 国际化 (i18n)
目录
为什么选择 Inlayer 而不是替代品？
与“svelte-i18n”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
完整的 SvelteKit 覆盖
Intlayer 经过优化，可与 SvelteKit 完美配合，提供多语言路由、SSR 支持以及扩展国际化 (i18n) 所需的所有功能。
捆绑尺寸
不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。
可维护性
确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。
人工智能代理
共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent技能，使 AI 代理的开发者体验 (DX) 更加流畅。
自动化
使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。
表现
将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
无需开发即可扩展
Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
在 SvelteKit 应用中设置 Intlayer 的分步指南
首先，创建一个新的 SvelteKit 项目。以下是我们将要构建的最终结构：
复制代码到剪贴板
.├── intlayer.config.ts├── package.json├── src│ ├── app.d.ts│ ├── app.html│ ├── hooks.server.ts│ ├── lib│ │ ├── getLocale.ts│ │ ├── LocaleSwitcher.svelte│ │ └── LocalizedLink.svelte│ ├── params│ │ └── locale.ts│ └── routes│ ├── [[locale=locale]]│ │ ├── +layout.svelte│ │ ├── +layout.ts│ │ ├── +page.svelte│ │ ├── +page.ts│ │ ├── about│ │ │ ├── +page.svelte│ │ │ ├── +page.ts│ │ │ └── page.content.ts│ │ ├── Counter.content.ts│ │ ├── Counter.svelte│ │ ├── Header.content.ts│ │ ├── Header.svelte│ │ ├── home.content.ts│ │ └── layout.content.ts│ ├── +layout.svelte│ └── layout.css├── static│ ├── favicon.svg│ └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts第一步：安装依赖
使用 npm 安装必要的包：
复制代码到剪贴板
npm install intlayer svelte-intlayernpm install vite-intlayer --save-devnpx intlayer init- intlayer：核心的国际化（i18n）包。
- svelte-intlayer：为 Svelte/SvelteKit 提供上下文提供者和存储。
- vite-intlayer：Vite 插件，用于将内容声明集成到构建流程中。
第二步：配置你的项目
在项目根目录创建一个配置文件：
复制代码到剪贴板
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, },};export default config;第3步：在你的 Vite 配置中集成 Intlayer
更新你的 vite.config.ts 文件以包含 Intlayer 插件。该插件负责内容文件的转译。
复制代码到剪贴板
import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [intlayer(), sveltekit()], // 顺序很重要，Intlayer 应该放在 SvelteKit 之前});第4步：声明您的内容
在您的 src 文件夹中的任意位置创建内容声明文件（例如，src/lib/content 或与组件放在一起）。这些文件使用 t() 函数为每个语言环境定义您的应用程序可翻译的内容。
第5步：在您的组件中使用 Intlayer
现在你可以在任何 Svelte 组件中使用 useIntlayer 函数。它返回一个响应式存储，当语言环境变化时会自动更新。该函数会自动遵循当前语言环境（无论是在 SSR 还是客户端导航期间）。
注意：
useIntlayer返回一个 Svelte 存储，因此你需要使用 `--- createdAt: 2025-11-20 updatedAt: 2026-05-31 title: 如何翻译您的 SvelteKit 应用 – 2025 年国际化 (i18n) 指南 description: 了解如何使您的 SvelteKit 网站支持多语言。按照文档使用服务器端渲染 (SSR) 进行国际化 (i18n) 和翻译。 keywords:
- 国际化
- 文档
- Intlayer
- SvelteKit
- JavaScript
- SSR slugs:
- doc
- environment
- sveltekit applicationTemplate: https://github.com/aymericzip/intlayer-sveltekit-template history:
- version: 7.1.10 date: 2025-11-20 changes: 初始化历史记录
使用 Intlayer 翻译您的 SvelteKit 网站 | 国际化 (i18n)
目录
什么是 Intlayer？
Intlayer 是一个创新的开源国际化 (i18n) 库，旨在简化现代 Web 应用中的多语言支持。它与 SvelteKit 的服务器端渲染 (SSR) 功能无缝协作。
使用 Intlayer，您可以：
- 通过组件级声明式字典轻松管理翻译。
- 动态本地化元数据、路由和内容。
- 通过自动生成的类型确保 TypeScript 支持。
- 利用 SvelteKit 的 SSR 实现对搜索引擎友好的国际化。
在 SvelteKit 应用中设置 Intlayer 的分步指南
首先，创建一个新的 SvelteKit 项目。以下是我们将要构建的最终结构：
复制代码到剪贴板
.├── intlayer.config.ts├── package.json├── src│ ├── app.d.ts│ ├── app.html│ ├── hooks.server.ts│ ├── lib│ │ ├── getLocale.ts│ │ ├── LocaleSwitcher.svelte│ │ └── LocalizedLink.svelte│ ├── params│ │ └── locale.ts│ └── routes│ ├── [[locale=locale]]│ │ ├── +layout.svelte│ │ ├── +layout.ts│ │ ├── +page.svelte│ │ ├── +page.ts│ │ ├── about│ │ │ ├── +page.svelte│ │ │ ├── +page.ts│ │ │ └── page.content.ts│ │ ├── Counter.content.ts│ │ ├── Counter.svelte│ │ ├── Header.content.ts│ │ ├── Header.svelte│ │ ├── home.content.ts│ │ └── layout.content.ts│ ├── +layout.svelte│ └── layout.css├── static│ ├── favicon.svg│ └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts第一步：安装依赖
使用 npm 安装必要的包：
复制代码到剪贴板
npm install intlayer svelte-intlayernpm install vite-intlayer --save-devnpx intlayer init- intlayer：核心的国际化（i18n）包。
- svelte-intlayer：为 Svelte/SvelteKit 提供上下文提供者和存储。
- vite-intlayer：Vite 插件，用于将内容声明集成到构建流程中。
第二步：配置你的项目
在项目根目录创建一个配置文件：
复制代码到剪贴板
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, },};export default config;第3步：在你的 Vite 配置中集成 Intlayer
更新你的 vite.config.ts 文件以包含 Intlayer 插件。该插件负责内容文件的转译。
复制代码到剪贴板
import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [intlayer(), sveltekit()], // 顺序很重要，Intlayer 应该放在 SvelteKit 之前});第4步：声明您的内容
在您的 src 文件夹中的任意位置创建内容声明文件（例如，src/lib/content 或与组件放在一起）。这些文件使用 t() 函数为每个语言环境定义您的应用程序可翻译的内容。
第5步：在您的组件中使用 Intlayer
前缀来访问其响应式值（例如，$content.title）。
复制代码到剪贴板
<script lang="ts"> import { useIntlayer } from "svelte-intlayer"; // "hero-section" 对应于步骤4中定义的键 const content = useIntlayer("hero-section");</script><!-- 以简单内容渲染内容 --><h1>{$content.title}</h1><!-- 使用编辑器渲染可编辑内容 --><h1>{@const Title = $content.title}<Title /></h1><!-- 以字符串形式渲染内容 --><div aria-label={$content.title.value}></div><div aria-label={$content.title.toString()}></div><div aria-label={String($content.title)}></div>设置路由
以下步骤展示了如何在 SvelteKit 中设置基于语言环境的路由。这允许您的 URL 包含语言环境前缀（例如
/en/about，/fr/about），以提升 SEO 和用户体验。bash复制代码复制代码到剪贴板
.└─── src ├── app.d.ts # 定义语言环境类型 ├── hooks.server.ts # 管理语言环境路由 ├── lib │ └── getLocale.ts # 从请求头、cookies 检查语言环境 ├── params │ └── locale.ts # 定义语言环境参数 └── routes ├── [[locale=locale]] # 使用路由组包裹以设置语言环境 │ ├── +layout.svelte # 路由的本地布局 │ ├── +layout.ts │ ├── +page.svelte │ ├── +page.ts │ └── about │ ├── +page.svelte │ └── +page.ts └── +layout.svelte # 字体和全局样式的根布局国际化链接
为了SEO，建议在路由前加上语言前缀（例如
/en/about，/fr/about）。该组件会自动为任何链接添加当前语言的前缀。src/lib/components/LocalizedLink.svelte复制代码复制代码到剪贴板
<script lang="ts"> import { getLocalizedUrl } from "intlayer"; import { useLocale } from "svelte-intlayer"; let { href = "" } = $props(); const { locale } = useLocale(); // 辅助函数：为URL添加当前语言前缀 $: localizedHref = getLocalizedUrl(href, $locale);</script><a href={localizedHref}> <slot /></a>如果你使用 SvelteKit 的
goto，可以用相同的逻辑结合getLocalizedUrl来跳转到本地化的URL：typescript复制代码复制代码到剪贴板
import { goto } from "$app/navigation";import { getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";const { locale } = useLocale();const localizedPath = getLocalizedUrl("/about", $locale);goto(localizedPath); // 根据语言环境导航到 /en/about 或 /fr/about语言切换器
为了允许用户切换语言，更新 URL。
src/lib/components/LanguageSwitcher.svelte复制代码复制代码到剪贴板
<script lang="ts"> import { getLocalizedUrl, getLocaleName } from 'intlayer'; import { useLocale } from "svelte-intlayer"; import { page } from '$app/stores'; import { goto } from '$app/navigation'; const { locale, setLocale, availableLocales } = useLocale({ onLocaleChange: (newLocale) => { const localizedPath = getLocalizedUrl($page.url.pathname, newLocale); goto(localizedPath); }, });</script><ul class="locale-list"> {#each availableLocales as localeEl} <li> <a href={getLocalizedUrl($page.url.pathname, localeEl)} onclick={(e) => { e.preventDefault(); setLocale(localeEl); // 将在存储中设置语言环境并触发 onLocaleChange }} class:active={$locale === localeEl} > {getLocaleName(localeEl)} </a> </li> {/each}</ul><style> /* */</style>添加后端代理
要为您的 SvelteKit 应用添加后端代理，可以使用
vite-intlayer插件提供的intlayerProxy函数。该插件将根据 URL、Cookie 和浏览器语言偏好自动检测用户的最佳语言环境。vite.config.ts复制代码复制代码到剪贴板
import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";import { sveltekit } from "@sveltejs/kit/vite";// https://vitejs.dev/config/export default defineConfig({ plugins: [ intlayerProxy(), // should be placed first intlayer(), sveltekit(), ],],});设置 intlayer 编辑器 / CMS
要设置 intlayer 编辑器，您必须遵循 intlayer 编辑器文档。
要设置 intlayer CMS，您必须遵循 intlayer CMS 文档。
要能够可视化 intlayer 编辑器选择器，您必须在 intlayer 内容中使用组件语法。
Component.svelte复制代码复制代码到剪贴板
<script lang="ts"> import { useIntlayer } from "svelte-intlayer"; const content = useIntlayer("component");</script><div> <!-- 以简单内容方式渲染内容 --> <h1>{$content.title}</h1> <!-- 以组件方式渲染内容（编辑器所需） --> {@const Component = $content.component}<Component /></div>提取组件内容
可选如果您有现有的代码库，转换数千个文件可能会非常耗时。
为了简化此过程，Intlayer 提出了 编译器 / 提取器 来转换您的组件并提取内容。
要进行设置，您可以在
intlayer.config.ts文件中添加compiler部分：intlayer.config.ts复制代码复制代码到剪贴板
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... 您的其他配置 compiler: { /** * 指示是否应启用编译器。 */ enabled: true, /** * 定义输出文件路径 */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。 */ saveComponents: false, /** * 字典键前缀 */ dictionaryKeyPrefix: "", }, }; export default config;运行提取器以转换组件并提取内容
bash复制代码复制代码到剪贴板
npx intlayer extract
第7步：处理服务器端的语言环境检测（Hooks）
在 SvelteKit 中，服务器需要知道用户的语言环境，以便在 SSR 期间渲染正确的内容。我们使用 hooks.server.ts 从 URL 或 cookie 中检测语言环境。
创建或修改 src/hooks.server.ts：
复制代码到剪贴板
import type { Handle } from "@sveltejs/kit";import { getLocalizedUrl } from "intlayer";import { getLocale } from "$lib/getLocale";export const handle: Handle = async ({ event, resolve }) => { const detectedLocale = getLocale(event); // 检查当前路径是否已以某个语言环境开头（例如 /fr, /en） const pathname = event.url.pathname; const targetPathname = getLocalizedUrl(pathname, detectedLocale); // 如果 URL 中没有语言环境（例如用户访问 "/"），则重定向 if (targetPathname !== pathname) { return new Response(undefined, { headers: { Location: targetPathname }, status: 307, // 临时重定向 }); } return resolve(event, { transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale), });};然后，创建一个辅助函数从请求事件中获取用户的语言环境：
复制代码到剪贴板
import { configuration, getLocaleFromStorage, localeDetector, type Locale,} from "intlayer";import type { RequestEvent } from "@sveltejs/kit";/** * 从请求事件中获取用户的语言环境。 * 此函数用于 `src/hooks.server.ts` 中的 `handle` 钩子。 * * 它首先尝试从 Intlayer 存储（cookies 或自定义头）中获取语言环境。 * 如果未找到语言环境，则回退到浏览器的 "Accept-Language" 协商。 * * @param event - 来自 SvelteKit 的请求事件 * @returns 用户的语言环境 */export const getLocale = (event: RequestEvent): Locale => { const defaultLocale = configuration?.internationalization?.defaultLocale; // 尝试从 Intlayer 存储（Cookies 或头）中获取语言环境 const storedLocale = getLocaleFromStorage({ // SvelteKit cookies 访问 getCookie: (name: string) => event.cookies.get(name) ?? null, // SvelteKit headers 访问 getHeader: (name: string) => event.request.headers.get(name) ?? null, }); if (storedLocale) { return storedLocale; } // 回退到浏览器的 "Accept-Language" 协商 const negotiatorHeaders: Record<string, string> = {}; // 将 SvelteKit Headers 对象转换为普通的 Record<string, string> event.request.headers.forEach((value, key) => { negotiatorHeaders[key] = value; }); // 从 `Accept-Language` 头检查语言环境 const userFallbackLocale = localeDetector(negotiatorHeaders); if (userFallbackLocale) { return userFallbackLocale; } // 如果没有匹配，返回默认语言环境 return defaultLocale;};getLocaleFromStorage 将根据您的配置从请求头或 cookie 中检查语言环境。更多详情请参见 Configuration。localeDetector函数会处理Accept-Language请求头并返回最佳匹配的语言环境。
如果未配置语言环境，我们希望返回 404 错误。为简化操作，我们可以创建一个 match 函数来检查语言环境是否有效：
复制代码到剪贴板
export const match = (param: Locale = defaultLocale): boolean => locales.includes(param);注意： 请确保您的
src/app.d.ts中包含语言环境的定义：typescript复制代码复制代码到剪贴板
declare global { namespace App { interface Locals { locale: import("intlayer").Locale; } }}
对于 +layout.svelte 文件，我们可以删除所有内容，只保留与国际化无关的静态内容：
复制代码到剪贴板
<script lang="ts"> import './layout.css'; let { children } = $props();</script><div class="app"> {@render children()}</div><style> .app { /* */ }</style>然后，在 [[locale=locale]] 组下创建一个新的页面和布局：
复制代码到剪贴板
import type { Load } from "@sveltejs/kit";import { defaultLocale, type Locale } from "intlayer";export const prerender = true;// 使用通用的 Load 类型export const load: Load = ({ params }) => { const locale: Locale = (params.locale as Locale) ?? defaultLocale; return { locale, };};复制代码到剪贴板
<script lang="ts"> import type { Snippet } from 'svelte'; import { useIntlayer, setupIntlayer } from "svelte-intlayer"; import Header from './Header.svelte'; import type { LayoutData } from './$types'; let { children, data }: { children: Snippet, data: LayoutData } = $props(); // 使用路由中的 locale 初始化 Intlayer $effect(() => { setupIntlayer(data.locale); }); // 使用布局内容字典 const layoutContent = useIntlayer('layout');</script><Header /><main> {@render children()}</main><footer> <p> {$layoutContent.footer.prefix.value}{' '} <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '} {$layoutContent.footer.suffix.value} </p></footer><style> /* */</style>复制代码到剪贴板
export const prerender = true;复制代码到剪贴板
<script lang="ts"> import { useIntlayer } from "svelte-intlayer"; // 使用主页内容字典 const homeContent = useIntlayer('home');</script><svelte:head> <title>{$homeContent.title.value}</title></svelte:head><section> <h1> {$homeContent.title} </h1></section><style> /* */</style>Git 配置
建议忽略 Intlayer 生成的文件。
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayer深入了解
- 可视化编辑器：集成Intlayer 可视化编辑器，以便直接从用户界面编辑翻译内容。
- CMS：使用Intlayer CMS实现内容管理的外部化。