作者:
    Aymeric PINEAU
    Creation:2025-04-18Last update:2026-06-23

    使用Intlayer翻译您的Vite and Solid | 国际化(i18n)

    www.youtube.com
    ide.intlayer.org
    intlayer-vite-solid.vercel.app

    目录

    为什么选择 Intlayer 而不是其他方案？

    与 @solid-primitives/i18n 或 i18next 等主要解决方案相比，Intlayer 是一个集成了优化功能的解决方案，例如：

    Intlayer 针对 Solid 进行了优化，提供 组件级内容作用域、响应式翻译 以及国际化 (i18n) 扩展所需的所有功能。

    不再将庞大的 JSON 文件加载到页面中，只加载必要的内容。Intlayer 帮助 将 bundle 和页面大小减少高达 50%。

    对应用程序的内容进行作用域划分 便于维护 大型应用程序。您可以复制或删除单个功能文件夹，而无需费力审查整个内容代码库。此外，Intlayer 完全类型化，确保内容的准确性。

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

    在 CI/CD 管道中使用自动化翻译，选择您的 LLM，按照 AI 提供商的成本计费。Intlayer 还提供 编译器 来自动提取内容，以及一个 web 平台 来帮助 后台翻译。

    将庞大的 JSON 文件连接到组件可能导致性能和反应性问题。Intlayer 在构建时优化了内容加载。

    Intlayer 不仅仅是一个 i18n 解决方案，它还提供 自托管 visual editor 和 完整 CMS 来帮助您 实时 管理多语言内容，使与翻译人员、文案撰写人和其他团队成员的协作无缝进行。内容可以本地存储和/或远程存储。

    Vite 和 Solid 应用程序中 Intlayer 的分步设置指南

    目录

    1. 安装依赖

      使用 npm 安装必要的包：

      bash
      npx intlayer init --interactive
      --interactive 标志是可选的。如果您是 AI agent，请使用 intlayer-cli init。
      此命令将检测您的环境并安装必要的包。例如：
      bash
      npm install intlayer solid-intlayer
npm install vite-intlayer --save-dev

      • intlayer

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

      • solid-intlayer 将 Intlayer 与 Solid 应用程序集成的包。它为 Solid 国际化提供上下文提供者和 hooks。

      • vite-intlayer 包括用于将 Intlayer 与 Vite bundler 集成的 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 solid from "vite-plugin-solid";
import { intlayer } from "vite-intlayer";

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

    4. 声明您的内容

      创建和管理您的内容声明来存储翻译：

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

const appContent = {
  key: "app",
  content: {
    viteLogo: t({
      zh: "Vite logo",
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    solidLogo: t({
      zh: "Solid logo",
      en: "Solid logo",
      fr: "Logo Solid",
      es: "Logo Solid",
    }),
    title: "Vite + Solid",
    count: t({
      zh: "计数为 {{count}}",
      en: "count is {{count}}",
      fr: "le compte est {{count}}",
      es: "el recuento es {{count}}",
    }),
    edit: t({
      zh: "编辑 src/App.tsx 并保存以测试 HMR",
      en: "Edit src/App.tsx and save to test HMR",
      fr: "Éditez src/App.tsx et enregistrez pour tester HMR",
      es: "Edita src/App.tsx y guarda para probar HMR",
    }),
    readTheDocs: t({
      zh: "点击 Vite 和 Solid logo 以了解更多",
      en: "Click on the Vite and Solid logos to learn more",
      fr: "Cliquez sur les logos Vite et Solid pour en savoir plus",
      es: "Haga clic en los logotipos de Vite and Solid para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

      您的内容声明可以在应用程序中的任何位置定义，只要它们包含在 contentDir 目录中（默认为 ./src）。并且匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

      有关更多详细信息，请参阅内容声明文档。

    5. 在您的代码中使用 Intlayer

      在整个应用程序中访问您的内容字典：

      src/App.tsx
      import { createSignal, type Component } from "solid-js";
import solidLogo from "./assets/solid.svg";
import viteLogo from "/vite.svg";
import "./App.css";
import { IntlayerProvider, useIntlayer } from "solid-intlayer";

const AppContent: Component = () => {
  const [count, setCount] = createSignal(0);
  const content = useIntlayer("app");

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
        </a>
        <a href="https://www.solidjs.com/" target="_blank">
          <img
            src={solidLogo}
            class="logo solid"
            alt={content.solidLogo.value}
          />
        </a>
      </div>
      <h1>{content.title}</h1>
      <div class="card">
        <button onClick={() => setCount((count) => count + 1)}>
          {content.count({ count: count() })}
        </button>
        <p>{content.edit}</p>
      </div>
      <p class="read-the-docs">{content.readTheDocs}</p>
    </>
  );
};

const App: Component = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;
      在 Solid 中，useIntlayer 返回反应式内容（例如 content）。您可以直接访问其属性。

      如果您想在 string 属性中使用您的内容，例如 alt、title、href、aria-label 等，您可以使用函数的值，如：

      html
      <img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />

    6. 更改内容的语言

      可选

      要更改内容的语言，您可以使用 useLocale hook 提供的 setLocale 函数。此函数允许您设置应用程序的语言环境并相应地更新内容。

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";
import { Locales } from "intlayer";
import { useLocale } from "solid-intlayer";

const LocaleSwitcher: Component = () => {
  const { locale, setLocale, availableLocales } = useLocale();

  return (
    <select
      value={locale()}
      onChange={(e) => setLocale(e.currentTarget.value as Locales)}
    >
      <For each={availableLocales}>
        {(loc) => (
          <option value={loc} selected={loc === locale()}>
            {loc}
          </option>
        )}
      </For>
    </select>
  );
};

    7. 为您的应用程序添加本地化路由

      可选

      此步骤的目的是为每种语言创建独特的路由。这对 SEO 和 SEO 友好的 URL 很有用。 示例：

      plaintext
      - https://example.com/about
- https://example.com/es/about
- https://example.com/fr/about

      要为您的应用程序添加本地化路由，您可以使用 @solidjs/router。

      首先，安装必要的依赖：

      bash
      npm install @solidjs/router

      然后，使用 Router 包装您的应用程序，并使用 localeMap 定义您的路由：

      src/index.tsx
      import { render } from "solid-js/web";
import { Router } from "@solidjs/router";
import App from "./App";

const root = document.getElementById("root");

render(
  () => (
    <Router>
      <App />
    </Router>
  ),
  root!
);
      src/App.tsx
      import { type Component } from "solid-js";
import { Route } from "@solidjs/router";
import { localeMap } from "intlayer";
import { IntlayerProvider } from "solid-intlayer";
import Home from "./pages/Home";
import About from "./pages/About";

const App: Component = () => (
  <IntlayerProvider>
    {localeMap(({ locale, urlPrefix }) => (
      <Route
        path={urlPrefix || "/"}
        component={(props: any) => (
          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>
        )}
      >
        <Route path="/" component={Home} />
        <Route path="/about" component={About} />
      </Route>
    ))}
  </IntlayerProvider>
);

export default App;

    8. 当语言环境更改时更改 URL

      可选

      要在语言环境更改时更改 URL，您可以使用 useLocale hook 提供的 onLocaleChange 属性。您可以使用 @solidjs/router 中的 useNavigate 和 useLocation hooks 来更新 URL 路径。

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";
import { useLocation, useNavigate } from "@solidjs/router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

const LocaleSwitcher: Component = () => {
  const location = useLocation();
  const navigate = useNavigate();
  const { locale, setLocale, availableLocales } = useLocale({
    onLocaleChange: (loc) => {
      const pathWithLocale = getLocalizedUrl(location.pathname, loc);
      navigate(pathWithLocale);
    },
  });

  return (
    <select
      value={locale()}
      onChange={(e) => setLocale(e.currentTarget.value as any)}
    >
      <For each={availableLocales}>
        {(loc) => (
          <option value={loc} selected={loc === locale()}>
            {loc}
          </option>
        )}
      </For>
    </select>
  );
};

    9. 切换 HTML 语言和方向属性

      可选

      更新 <html> 标签的 lang 和 dir 属性以匹配当前的语言环境，以提高可访问性和 SEO。

      src/App.tsx
      import { createEffect, type Component } from "solid-js";
import { useLocale } from "solid-intlayer";
import { getHTMLTextDir } from "intlayer";

const AppContent: Component = () => {
  const { locale } = useLocale();

  createEffect(() => {
    document.documentElement.lang = locale();
    document.documentElement.dir = getHTMLTextDir(locale());
  });

  return (
    // ... 您的应用程序内容
  );
};

    10. 创建本地化链接组件

      可选

      创建一个自定义 Link 组件，该组件自动为内部 URL 添加当前语言的前缀。

      src/components/Link.tsx
      import { type ParentComponent } from "solid-js";
import { A, type AnchorProps } from "@solidjs/router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

export const Link: ParentComponent<AnchorProps> = (props) => {
  const { locale } = useLocale();

  const isExternal = () => props.href.startsWith("http");
  const localizedHref = () =>
    isExternal() ? props.href : getLocalizedUrl(props.href, locale());

  return <A {...props} href={localizedHref()} />;
};

      同时，您也可以使用 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 solid from "vite-plugin-solid";
import { intlayer } from "vite-intlayer";

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

    11. 提取您的组件的内容

      可选

      如果您有现有的 codebase，转换数千个文件可能很耗时。

      为了简化此过程，Intlayer 提供了一个 compiler / extractor 来转换您的组件并提取内容。

      要设置它，您可以在 intlayer.config.ts 文件中添加 compiler 部分：

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 您的其他配置
  compiler: {
    /**
     * 指示是否应启用编译器。
     */
    enabled: true,

    /**
     * 定义输出文件路径
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 指示转换后是否应保存组件。
     *
     * - 如果为 `true`，编译器将重写磁盘中的组件文件。因此转换将是永久的，编译器将跳过下一个过程的转换。这样，编译器可以转换应用程序，然后可以将其删除。
     *
     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，并保持基础 codebase 完整。转换仅在内存中进行。
     */
    saveComponents: false,

    /**
     * 字典键前缀
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      运行提取器来转换您的组件并提取内容

      bash
      npx intlayer extract
      自从 v9 以来，intlayerCompiler 已包含在 intlayer 插件中。因此您无需手动添加它。

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

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

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // 添加编译器插件
  ],
});
      bash
      npm run build # 或 npm run dev

    第3步：在你的 Vite 配置中集成 Intlayer

    intlayer() 是用于将 Intlayer 集成到 Vite 中的插件。它确保内容声明文件的构建，并在开发模式下监视这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。

    网站地图

    Intlayer 的网站地图生成器尊重您的语言环境设置，并包含爬虫程序的常见元数据。

    生成的网站地图支持 xhtml:link 命名空间（hreflang XML 扩展）。与仅发出平面 URL 的基本生成器不同，Intlayer 在每个页面的每个本地化变体之间建立双向链接（例如 /about、/fr/about 或 /about?lang=fr，具体取决于您的路由模式），这有助于搜索引擎关联本地化 URL。

    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);

// 获取所有多语言 URL
const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

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

// 生成 robots.txt
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 ESM 的 generate-seo.mjs。如果改用 generate-seo.js，请确保在 package.json 中设置 "type": "module"，或使用 ESM 启用的方式运行 Node。

    2. 在 Vite 之前运行脚本

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

    如果你使用 pnpm 或 yarn，请相应调整。你也可以从 CI 或其他步骤中调用相同的脚本，如果这适合你的工作流程。

    配置 TypeScript

    确保您的 TypeScript 配置包含自动生成的类型。

    tsconfig.json
    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    Git 配置

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

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

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

    VS Code 扩展

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

    从 VS Code 市场安装

    深入了解

    要进一步使用，您可以实现可视化编辑器或使用内容管理系统（CMS）将内容外部化。

    Nuxt和VueSolid Start