@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.6

package/docs/zh/intlayer_with_svelte_kit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-20
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "SvelteKit i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) SvelteKit 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -94,342 +94,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 SvelteKit 应用中设置 Intlayer 的分步指南
-
-首先，创建一个新的 SvelteKit 项目。以下是我们将要构建的最终结构：
-
-```bash
-.
-├── 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 安装必要的包：
-
-```bash packageManager="npm"
-npx intlayer-cli init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer-cli init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer-cli init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer-cli init --interactive
-```
-
-> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
-
-> 该命令将检测您的环境并安装所需的软件包。例如：
-
-```bash packageManager="npm"
-npm install intlayer svelte-intlayer
-npm install vite-intlayer --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer svelte-intlayer
-pnpm add vite-intlayer --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer svelte-intlayer
-yarn add vite-intlayer --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer svelte-intlayer
-bun add vite-intlayer --save-dev
-```
-
-- **intlayer**：核心的国际化（i18n）包。
-- **svelte-intlayer**：为 Svelte/SvelteKit 提供上下文提供者和存储。
-- **vite-intlayer**：Vite 插件，用于将内容声明集成到构建流程中。
-
-### 第二步：配置你的项目
-
-在项目根目录创建一个配置文件：
-
-```typescript fileName="intlayer.config.ts"
-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 插件。该插件负责内容文件的转译。
-
-```typescript fileName="vite.config.ts"
-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()` 函数为每个语言环境定义您的应用程序可翻译的内容。
-
-```ts fileName="src/features/hero/hero.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { t, type Dictionary } from "intlayer";
-
-const heroContent = {
-  key: "hero-section",
-  content: {
-    title: t({
-      en: "Welcome to SvelteKit",
-      fr: "Bienvenue sur SvelteKit",
-      es: "Bienvenido a SvelteKit",
-    }),
-  },
-} satisfies Dictionary;
-
-export default heroContent;
-```
-
-### 第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)
-
-## 目录
-
-<TOC/>
-
-## 什么是 Intlayer？
-
-**Intlayer** 是一个创新的开源国际化 (i18n) 库，旨在简化现代 Web 应用中的多语言支持。它与 **SvelteKit** 的服务器端渲染 (SSR) 功能无缝协作。
-
-使用 Intlayer，您可以：
-
-- **通过组件级声明式字典轻松管理翻译**。
-- **动态本地化元数据、路由和内容**。
-- **通过自动生成的类型确保 TypeScript 支持**。
-- **利用 SvelteKit 的 SSR 实现对搜索引擎友好的国际化**。
-
----
-
-## 在 SvelteKit 应用中设置 Intlayer 的分步指南
-
-首先，创建一个新的 SvelteKit 项目。以下是我们将要构建的最终结构：
-
-```bash
-.
-├── 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 安装必要的包：
-
-```bash packageManager="npm"
-npx intlayer-cli init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer-cli init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer-cli init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer-cli init --interactive
-```
-
-> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
-
-> 该命令将检测您的环境并安装所需的软件包。例如：
-
-```bash packageManager="npm"
-npm install intlayer svelte-intlayer
-npm install vite-intlayer --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer svelte-intlayer
-pnpm add vite-intlayer --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer svelte-intlayer
-yarn add vite-intlayer --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer svelte-intlayer
-bun add vite-intlayer --save-dev
-```
-
-- **intlayer**：核心的国际化（i18n）包。
-- **svelte-intlayer**：为 Svelte/SvelteKit 提供上下文提供者和存储。
-- **vite-intlayer**：Vite 插件，用于将内容声明集成到构建流程中。
-
-### 第二步：配置你的项目
-
-在项目根目录创建一个配置文件：
-
-```typescript fileName="intlayer.config.ts"
-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 插件。该插件负责内容文件的转译。
-
-```typescript fileName="vite.config.ts"
-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()` 函数为每个语言环境定义您的应用程序可翻译的内容。
-
-```ts fileName="src/features/hero/hero.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { t, type Dictionary } from "intlayer";
-
-const heroContent = {
-  key: "hero-section",
-  content: {
-    title: t({
-      en: "Welcome to SvelteKit",
-      fr: "Bienvenue sur SvelteKit",
-      es: "Bienvenido a SvelteKit",
-    }),
-  },
-} satisfies Dictionary;
-
-export default heroContent;
-```
-
 ### 第5步：在您的组件中使用 Intlayer
 
 前缀来访问其响应式值（例如，`$content.title`）。
@@ -706,218 +370,6 @@ bun run build # Or bun run dev
 
 </Steps>
 
-### 第7步：处理服务器端的语言环境检测（Hooks）
-
-在 SvelteKit 中，服务器需要知道用户的语言环境，以便在 SSR 期间渲染正确的内容。我们使用 `hooks.server.ts` 从 URL 或 cookie 中检测语言环境。
-
-创建或修改 `src/hooks.server.ts`：
-
-```typescript fileName="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),
-  });
-};
-```
-
-然后，创建一个辅助函数从请求事件中获取用户的语言环境：
-
-```typescript fileName="src/lib/getLocale.ts"
-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](https://intlayer.org/doc/configuration)。
-
-> `localeDetector` 函数会处理 `Accept-Language` 请求头并返回最佳匹配的语言环境。
-
-如果未配置语言环境，我们希望返回 404 错误。为简化操作，我们可以创建一个 `match` 函数来检查语言环境是否有效：
-
-```ts fileName="/src/params/locale.ts"import { defaultLocale, locales, type Locale } from "intlayer";
-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` 文件，我们可以删除所有内容，只保留与国际化无关的静态内容：
-
-```svelte fileName="src/+layout.svelte"
-<script lang="ts">
-	 import './layout.css';
-
-    let { children } = $props();
-</script>
-
-<div class="app">
-	{@render children()}
-</div>
-
-<style>
-	.app {
-    /*  */
-	}
-</style>
-```
-
-然后，在 `[[locale=locale]]` 组下创建一个新的页面和布局：
-
-```ts fileName="src/routes/[[locale=locale]]/+layout.ts"
-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,
-  };
-};
-```
-
-```svelte fileName="src/routes/[[locale=locale]]/+layout.svelte"
-<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>
-```
-
-```ts fileName="src/routes/[[locale=locale]]/+page.ts"
-export const prerender = true;
-```
-
-```svelte fileName="src/routes/[[locale=locale]]/+page.svelte"
-<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 生成的文件。