作者:
    Aymeric PINEAU
    Creation:2025-04-18Last update:2026-08-30

    使用 Intlayer 翻译您的 Vite 和 Svelte 网站 | 国际化 (i18n)

    ide.intlayer.org
    intlayer-vite-svelte-template.vercel.app

    目录

    为什么选择 Inlayer 而不是替代品？

    与“svelte-i18n”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：

    Intlayer 经过优化，可与 Svelte 完美配合，提供组件级内容范围、反应式翻译以及​​扩展国际化 (i18n) 所需的所有功能。

    不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。

    确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。

    共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent skills，使 AI 代理的开发者体验 (DX) 更加流畅。

    使用您选择 of 法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。

    将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。

    Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地 and/or 远程存储。

    在 Vite 和 Svelte 应用中设置 Intlayer 的分步指南

    ide.intlayer.org

    请参阅 GitHub 上的应用模板。

    1. 安装依赖

      使用 npm 安装必要的包：

      bash
      npx intlayer init --interactive
      --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
      该命令将检测您的环境并安装所需的软件包。例如：
      bash
      npm install intlayer svelte-intlayer
npm install vite-intlayer --save-dev

      • intlayer

        核心包，提供国际化工具，用于配置管理、翻译、内容声明、转译以及CLI 命令。

      • svelte-intlayer 将 Intlayer 与 Svelte 应用程序集成的包。它提供了用于 Svelte 国际化的上下文提供者和钩子。

      • vite-intlayer 包含用于将 Intlayer 集成到 Vite 打包工具 的 Vite 插件，以及用于检测用户首选语言环境、管理 Cookie 和处理 URL 重定向的中间件。

    2. 配置您的项目

      创建一个配置文件来配置您的应用程序语言：

      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;
      通过此配置文件，您可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。

    3. 在您的 Vite 配置中集成 Intlayer

      将 intlayer 插件添加到您的配置中。

      vite.config.ts
      import { defineConfig } from "vite";
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [svelte(), intlayer()],
});
      intlayer() Vite 插件用于将 Intlayer 集成到 Vite 中。它确保内容声明文件的构建，并在开发模式下监控这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。

    4. 声明您的内容

      创建并管理您的内容声明以存储翻译：

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: t({
      en: "Hello World",
      fr: "Bonjour le monde",
      es: "Hola mundo",
    }),
  },
} satisfies Dictionary;

export default appContent;
      您的内容声明可以定义在应用程序中的任何位置，只要它们被包含在 contentDir 目录中（默认是 ./src），并且文件扩展名符合内容声明文件扩展名（默认是 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。
      更多详情，请参阅内容声明文档。

    5. 在代码中使用 Intlayer

      src/App.svelte
      <script>
  import { useIntlayer } from "svelte-intlayer";

  const content = useIntlayer("app");
</script>

<div>


<!-- 以简单内容渲染内容 -->
<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>
      如果您的应用程序已经存在，您可以结合使用 Intlayer 编译器 和 提取命令 在一秒钟内转换成干个组件。

    6. 更改内容语言

      src/App.svelte
      <script lang="ts">
import  { getLocaleName } from 'intlayer';
import { useLocale } from "svelte-intlayer";

// 获取语言信息和 setLocale 函数
const { locale, availableLocales, setLocale } = useLocale();

// 处理语言切换
const changeLocale = (event: Event) => {
  const target = event.target as HTMLSelectElement;
  const newLocale = target.value;
  setLocale(newLocale);
};
</script>

<div>
  <select value={$locale} on:change={changeLocale}>
    {#each availableLocales ?? [] as loc}
      <option value={loc}>
        {getLocaleName(loc)}
      </option>
    {/each}
  </select>
</div>

    7. 渲染Markdown

      Intlayer支持在您的Svelte应用中直接渲染Markdown内容。默认情况下，Markdown被视为纯文本。要将Markdown转换为丰富的HTML，您可以集成@humanspeak/svelte-markdown或其他markdown解析器。

      要了解如何使用intlayer包声明markdown内容，请参阅markdown文档。
      src/App.svelte
      <script>
  import { setIntlayerMarkdown } from "svelte-intlayer";

  setIntlayerMarkdown((markdown) =>
   // 将 markdown 内容渲染为字符串
   return markdown;
  );
</script>

<h1>{$content.markdownContent}</h1>
      你也可以通过 content.markdownContent.metadata.xxx 属性访问你的 markdown front-matter 数据。

    8. 设置 intlayer 编辑器 / CMS

      要设置 intlayer 编辑器，你必须遵循 intlayer 编辑器文档。

      要设置 intlayer CMS，你必须遵循 intlayer CMS 文档。

    9. 为你的应用程序添加本地化路由

      为了在你的 Svelte 应用程序中处理本地化路由，你可以使用 svelte-spa-router，并结合 Intlayer 的 localeFlatMap 来为每个语言环境生成路由。

      首先，安装 svelte-spa-router：

      bash
      npm install svelte-spa-router
npx intlayer init

      然后，创建一个 Router.svelte 文件来定义你的路由：

      src/Router.svelte
      <script lang="ts">
import { localeFlatMap } from "intlayer";
import Router from "svelte-spa-router";
import { wrap } from "svelte-spa-router/wrap";
import App from "./App.svelte";

const routes = Object.fromEntries(
    localeFlatMap(({locale, urlPrefix}) => [
    [
        urlPrefix || '/',
        wrap({
            component: App as any,
            props: {
                locale,
            },
        }),
    ],
    ])
);
</script>

<Router {routes} />

      更新你的 main.ts，将挂载的组件从 App 改为 Router：

      src/main.ts
      import { mount } from "svelte";
import Router from "./Router.svelte";

const app = mount(Router, {
  target: document.getElementById("app")!,
});

export default app;

      最后，更新你的 App.svelte 以接收 locale 属性并使用 useIntlayer：

      src/App.svelte
      <script lang="ts">
import type { Locale } from 'intlayer';
import { useIntlayer } from "svelte-intlayer";
import Counter from './lib/Counter.svelte';
import LocaleSwitcher from './lib/LocaleSwitcher.svelte';

export let locale: Locale;

$: content = useIntlayer('app', locale);
</script>

<main>
  <div class="locale-switcher-container">
    <LocaleSwitcher currentLocale={locale} />
  </div>

  <!-- ... 你的应用其余部分 ... -->
</main>

      配置服务器端路由（可选）

      同时，您还可以使用 intlayerProxy 为您的应用程序添加服务器端路由。该插件会根据 URL 自动检测当前的语言环境，并设置相应的语言环境 cookie。如果未指定语言环境，插件将根据用户浏览器的语言偏好确定最合适的语言环境。如果未检测到任何语言环境，它将重定向到默认语言环境。

      注意，要在生产环境中使用 intlayerProxy，您需要将 vite-intlayer 包从 devDependencies 切换到 dependencies。
      自 Intlayer v9 起，intlayerProxy() 已直接捆绑到 intlayer() 插件中，并默认通过 routing.enableProxy 选项（默认为 true）启用。如上所示单独注册现在是可选的——保留它是为了向后兼容以及需要控制插件顺序的设置。设置 routing.enableProxy: false 以退出。请参阅 v9 发布说明。
      vite.config.ts
      import { defineConfig } from "vite";
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    svelte(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

    10. 当语言环境变化时更改 URL

      可选

      为了允许用户切换语言并相应地更新 URL，您可以创建一个 LocaleSwitcher 组件。该组件将使用来自 intlayer 的 getLocalizedUrl and 来自 svelte-spa-router 的 push。

      src/lib/LocaleSwitcher.svelte
      <script lang="ts">
import { getLocaleName, getLocalizedUrl } from "intlayer";
import { useLocale } from "svelte-intlayer";
import { push } from "svelte-spa-router";

export let currentLocale: string | undefined = undefined;

// 获取语言环境信息
const { locale, availableLocales } = useLocale();

// 处理语言环境变化
const changeLocale = (event: Event) => {
  const target = event.target as HTMLSelectElement;
  const newLocale = target.value;
  const currentUrl = window.location.pathname;
  const url = getLocalizedUrl( currentUrl, newLocale);
  push(url);
};
</script>

<div class="locale-switcher">
  <select value={currentLocale ?? $locale} onchange={changeLocale}>
    {#each availableLocales ?? [] as loc}
      <option value={loc}>
        {getLocaleName(loc)}
      </option>
    {/each}
  </select>
</div>

    11. 国际化链接

      可选

      为了利于 SEO，建议在路由前加上语言环境前缀（例如，/about，/fr/about）。

      src/lib/components/Link.svelte
      <script lang="ts">
  import { getLocalizedUrl } from "intlayer";
  import { useLocale } from "svelte-intlayer";

  export let href = "";
  const { locale } = useLocale();

  // 辅助前缀 URL
  $: localizedHref = getLocalizedUrl(href, $locale);
</script>

<a href={localizedHref}>
  <slot />
</a>

    12. 提取组件内容

      可选

      如果您有现有的代码库，转换数千个文件可能会非常耗时。

      为了简化此过程，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
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      更新您的 vite.config.ts 以包含 intlayerCompiler 插件：

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # 或 npm run dev

    （可选）站点地图与 robots.txt（构建时生成）

    Intlayer 提供 generateSitemap 与 getMultilingualUrls，可将面向爬虫的多语言 sitemap.xml 和 robots.txt 格式化并自动写入 public/。实践中在 Vite 之前运行小型 Node 脚本（例如 npm 的 predev / prebuild）即可在构建或开发时生成这些文件。

    站点地图

    Intlayer 的站点地图生成会尊重你的语言配置，并包含爬虫所需的元数据。

    生成的站点地图支持 xhtml:link（hreflang）。与只列出扁平 URL 不同，Intlayer 会在各语言版本之间建立双向关联（例如 /about、/fr/about 或 /about?lang=fr，取决于路由模式）。

    Robots.txt

    使用 getMultilingualUrls，使 Disallow 覆盖敏感路径的每一种本地化写法。

    1. 在项目根目录添加 generate-seo.mjs

    generate-seo.mjs
    import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

    需已安装 intlayer 以便脚本导入。生产环境请设置环境变量 SITE_URL（例如在 CI 中）。

    建议在 Node 中使用 generate-seo.mjs（ESM）。若使用 generate-seo.js，请在 package.json 中设置 "type": "module" 或以其他方式启用 ESM。

    2. 在运行 Vite 之前执行脚本

    package.json
    {
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

    若使用 pnpm 或 yarn，请相应调整命令；也可在 CI 或其他步骤中调用该脚本。

    Git 配置

    建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。

    为此，您可以在 .gitignore 文件中添加以下指令：

    bash
    # 忽略 Intlayer 生成的文件
.intlayer

    VS Code 扩展

    为了提升使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。

    从 VS Code 市场安装

    此扩展提供：

    • 翻译键的自动补全。
    • 缺失翻译的实时错误检测。
    • 翻译内容的内联预览。
    • 轻松创建和更新翻译的快速操作。

    有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。

    深入了解

    要进一步提升，您可以实现可视化编辑器或使用CMS将内容外部化。

    常见问题

    Vite 本身对 i18n 没有特定偏好，因此选择主要来自 Svelte 生态：

    • svelte-i18n 和 typesafe-i18n：基于 Store 的全局注册消息目录。
    • Paraglide：编译型消息方案，仅专注于消息层。
    • Intlayer：最先进的解决方案。内容可以在代码库中的任何位置声明（靠近每个组件或集中管理），并在构建时由 Vite 插件进行编译，完全类型安全，并配有 AI 翻译、可视化编辑器和 CMS。

    对 Vite 而言，最大优势在于翻译在编译时解析并执行 tree-shaking，而不是在运行时以 JSON 形式获取，因此页面仅输出其渲染所需的条目。请参阅 为什么选择 Intlayer 和 性能基准。

    远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。构建时编译器将 useIntlayer 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 动态字典 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 Bundle 体积优化 和 性能基准。

    基本可以。请按照 Svelte I18n 迁移指南 迁移内容。您也可以逐步迁移：JSON 同步插件 将现有的 JSON 目录作为单一真实来源（source of truth），并生成 Intlayer 字典，使两个层在逐个组件迁移时保持同步。

    可以。JSON 同步插件 将您的 /messages/{locale}/{namespace}.json 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。PO 同步插件 对 gettext 目录执行相同的操作，而 按语言环境组织的文件 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。

    不需要。运行 npx intlayer extract，Intlayer 会读取您的组件，提取面向用户的字符串，并在每个组件旁边生成 .content 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。本指南的第 10 步详细介绍了此过程。

    如需全自动流程，Intlayer Compiler 可在构建时执行相同操作：它在每次更改时扫描您的 JSX、TSX、Vue 和 Svelte 源代码，生成字典并通过热模块替换 (HMR) 保持同步，因此完全无需手动维护键名。

    开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 className="active" 或状态代码），在大型代码库中需要少量注解。而 extract 命令 则通过让您参与审查避免了这两个问题。

    共有 5 个工具，均为可选：

    • VS Code 扩展：从 useIntlayer 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
    • LSP 服务器：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 i18next、react-i18next、next-intl 和 use-intl 调用，助力平滑迁移。
    • MCP 服务器：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 intlayer fill 等命令。
    • Agent Skills：针对特定领域的技能（如 intlayer-config、intlayer-cli 和 intlayer-content，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
    • ESLint 插件：no-raw-text 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
    Solid StartSvelteKit