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

目录

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

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

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

目录

1. 1

   安装依赖

   使用 npm 安装必要的包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive

   --interactive 标志是可选的。如果您是 AI agent，请使用 intlayer-cli init。

   此命令将检测您的环境并安装必要的包。例如：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer solid-intlayernpm install vite-intlayer --save-dev

   • intlayer

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

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

   • vite-intlayer 包括用于将 Intlayer 与 Vite bundler 集成的 Vite 插件，以及用于检测用户首选语言、管理 cookie 和处理 URL 重定向的中间件。

2. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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;

    Extract commandBabel compiler

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

    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 插件添加到你的配置中。

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), 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

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);// 获取所有多语言 URLconst getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);// 生成 robots.txtconst 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 之前运行脚本

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

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

配置 TypeScript

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

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

Git 配置

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

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

#  忽略 Intlayer 生成的文件.intlayer

VS Code 扩展

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

从 VS Code 市场安装

该扩展提供：

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

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

深入了解

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