接收有关即将发布的Intlayer的通知
    Creation:2025-04-18Last update:2025-11-19

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

    目录

    什么是 Intlayer？

    Intlayer 是一个创新的开源国际化 (i18n) 库，旨在简化现代 Web 应用的多语言支持。

    使用 Intlayer，您可以：

    • 通过组件级声明式字典轻松管理翻译。
    • 动态本地化元数据、路由和内容。
    • 确保 TypeScript 支持，通过自动生成类型提升自动补全和错误检测。
    • 享受高级功能，如动态语言环境检测和切换。

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

    请参阅 GitHub 上的应用模板。

    第一步：安装依赖

    使用 npm 安装必要的包：

    npm install intlayer svelte-intlayernpm 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 日志等。有关可用参数的完整列表，请参阅配置文档。

    第三步：在您的 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 的环境变量。此外，它还提供别名以优化性能。

    第四步：声明您的内容

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

    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,mjx,cjs,cjx}）。
    更多详情，请参阅内容声明文档。

    第5步：在代码中使用 Intlayer

    src/App.svelte
    <script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- 以简单内容渲染内容 --><h1>{$content.title}</h1><!-- 使用编辑器渲染可编辑内容 --><h1><svelte:component this={$content.title} /></h1><!-- 以字符串形式渲染内容 --><div aria-label={$content.title.value}></div>

    （可选）步骤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 文档。

    在你的 Svelte 应用程序中，同时你必须在布局文件或应用程序的根目录中添加以下代码行：

    src/layout.svelte
    import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

    （可选）步骤 7：为你的应用程序添加本地化路由

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

    首先，安装 svelte-spa-router：

    npm install svelte-spa-router

    然后，创建一个 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。
    vite.config.ts
    import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer(), intlayerProxy()],});

    （可选）步骤 8：当语言环境改变时更改 URL

    为了允许用户切换语言并相应地更新 URL，您可以创建一个 LocaleSwitcher 组件。该组件将使用 intlayer 中的 getLocalizedUrl 和 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) => {  plugins: [svelte(), intlayer(), intlayerProxy()],});

    （可选）步骤 8：当语言环境变化时更改 URL

    为了允许用户切换语言并相应地更新 URL，您可以创建一个 LocaleSwitcher 组件。该组件将使用来自 intlayer 的 getLocalizedUrl 和来自 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>

    Git 配置

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

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

    # 忽略 Intlayer 生成的文件.intlayer

    VS Code 扩展

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

    从 VS Code 市场安装

    该扩展提供：

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

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

    深入了解

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

    Vite和Solid
    SvelteKit
    接收有关即将发布的Intlayer的通知