Creation:2025-03-09Last update:2026-05-31

    使用Intlayer翻译您的Lynx and React mobile app | 国际化(i18n)

    请参阅 GitHub 上的应用模板。

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

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

    完整的山猫覆盖

    Intlayer 经过优化，可与 Lynx 和 React 完美配合，提供组件级内容范围、TypeScript 支持以及扩展国际化 (i18n) 所需的所有功能。

    捆绑尺寸

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

    可维护性

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

    人工智能代理

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

    自动化

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

    表现

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

    无需开发即可扩展

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

    第一步：安装依赖

    在您的 Lynx 项目中，安装以下包：

    bash
    npm install intlayer react-intlayer lynx-intlayernpx intlayer init

    包说明

    • intlayer
      核心 i18n 工具包，用于配置、字典内容、类型生成和 CLI 命令。

    • react-intlayer
      React 集成，提供上下文提供者和 React hooks，您将在 Lynx 中使用它来获取和切换语言。

    • lynx-intlayer
      Lynx 集成，提供将 Intlayer 与 Lynx 打包器集成的插件。

    第二步：创建 Intlayer 配置

    在项目根目录（或任何方便的位置）创建一个 Intlayer 配置 文件。它可能如下所示：

    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;

    在此配置中，您可以：

    • 配置您的支持语言列表。
    • 设置一个默认语言。
    • 以后，您可以添加更高级的选项（例如日志、自定义内容目录等）。
    • 查看 Intlayer 配置文档 了解更多。

    第三步：将 Intlayer 插件添加到 Lynx 打包器

    要在 Lynx 中使用 Intlayer，您需要将插件添加到 lynx.config.ts 文件中：

    lynx.config.ts
    import { defineConfig } from "@lynx-js/rspeedy";import { pluginIntlayerLynx } from "lynx-intlayer/plugin";export default defineConfig({  plugins: [    // ... 其他插件    pluginIntlayerLynx(),  ],});

    第四步：添加 Intlayer 提供者

    为了在您的应用程序中同步用户语言，您需要使用 react-intlayer 中的 IntlayerProvider 组件包装您的根组件。

    此外，您需要添加 intlayerPolyfill 函数文件，以确保 Intlayer 能够正常工作。

    src/index.tsx
    import { root } from "@lynx-js/react";import { App } from "./App.js";import { IntlayerProvider } from "react-intlayer";import { intlayerPolyfill } from "lynx-intlayer";intlayerPolyfill();root.render(  <IntlayerProvider>    <App />  </IntlayerProvider>);if (import.meta.webpackHot) {  import.meta.webpackHot.accept();}

    第五步：声明您的内容

    在项目中的任何位置创建内容声明文件（通常在 src/ 中），使用 Intlayer 支持的任何扩展格式：

    • .content.json
    • .content.ts
    • .content.tsx
    • .content.js
    • .content.jsx
    • .content.mjs
    • .content.mjx
    • .content.cjs
    • .content.cjx
    • 等等。

    示例：

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

const appContent = {
  key: "app",
  content: {
    title: "React",
    subtitle: t({
      en: "on Lynx",
      fr: "sur Lynx",
      es: "en Lynx",
    }),
    description: t({
      zh: "点击标志并享受乐趣！",
      en: "Tap the logo and have fun!",
      fr: "Appuyez sur le logo et amusez-vous!",
      es: "¡Toca el logo y diviértete!",
    }),
    hint: [
      t({
        zh: "编辑",
        en: "Edit",
        fr: "Modifier",
        es: "Editar",
      }),
      " src/App.tsx ",
      t({
        zh: "以查看更新！",
        en: "to see updates!",
        fr: "pour voir les mises à jour!",
        es: "para ver actualizaciones!",
      }),
    ],
  },
} satisfies Dictionary;

export default appContent;
    有关内容声明的详细信息，请参阅 Intlayer 的内容文档。

    第 4 步：在组件中使用 Intlayer

    在子组件中使用 useIntlayer 钩子以获取本地化内容。

    src/App.tsx
    import { useCallback, useState } from "@lynx-js/react";import { useIntlayer } from "react-intlayer";import "./App.css";import arrow from "./assets/arrow.png";import lynxLogo from "./assets/lynx-logo.png";import reactLynxLogo from "./assets/react-logo.png";import { LocaleSwitcher } from "./components/LocaleSwitcher.jsx";export const App = () => {  const [alterLogo, setAlterLogo] = useState(false);  const { title, subtitle, description, hint } = useIntlayer("app");  const onTap = useCallback(() => {    // 仅更改背景    setAlterLogo(!alterLogo);  }, [alterLogo]);  return (    <view>      <view className="Background" />      <view className="App">        <view className="Banner">          <view className="Logo" bindtap={onTap}>            {alterLogo ? (              <image src={reactLynxLogo} className="Logo--react" />            ) : (              <image src={lynxLogo} className="Logo--lynx" />            )}          </view>          <text className="Title">{title}</text>          <text className="Subtitle">{subtitle}</text>        </view>        <view className="Content">          <image src={arrow} className="Arrow" />          <text className="Description">{description}</text>          <text className="Hint">            {hint[0]}            <text style={{ fontStyle: "italic" }}>{hint[1]}</text>            {hint[2]}          </text>        </view>        <LocaleSwitcher />        <view style={{ flex: 1 }}></view>      </view>    </view>  );};
    当在基于字符串的属性中使用 content.someKey（例如按钮的 title 或 Text 组件的 children）时，调用 content.someKey.value 以获取实际字符串。

    （可选）第 5 步：更改应用程序语言环境

    要从组件内部切换语言环境，可以使用 useLocale 钩子的 setLocale 方法：

    src/components/LocaleSwitcher.tsx
    import { type FC } from "react";import { getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale, availableLocales, locale } = useLocale();  return (    <view      style={{        display: "flex",        flexDirection: "row",        justifyContent: "center",        alignItems: "center",        gap: 10,      }}    >      {availableLocales.map((localeEl) => (        <text          key={localeEl}          style={{            color: localeEl === locale ? "#fff" : "#888",            fontSize: "12px",          }}          bindtap={() => setLocale(localeEl)}        >          {getLocaleName(localeEl)}        </text>      ))}    </view>  );};

    这将触发使用 Intlayer 内容的所有组件的重新渲染，现在显示新语言环境的翻译。

    有关更多详细信息，请参阅 useLocale 文档。

    配置 TypeScript（如果您使用 TypeScript）

    Intlayer 在一个隐藏文件夹中生成类型定义（默认是 .intlayer），以改进自动补全并捕获翻译错误：

    json5
    // tsconfig.json{  // ... 您现有的 TS 配置  "include": [    "src", // 您的源代码    ".intlayer/types/**/*.ts", // <-- 确保包含自动生成的类型    // ... 您已经包含的其他内容  ],}

    这使得以下功能成为可能：

    • 自动补全 您的字典键。
    • 类型检查 如果您访问不存在的键或类型不匹配，将发出警告。

    Git 配置

    为了避免提交由 Intlayer 自动生成的文件，请将以下内容添加到您的 .gitignore 中：

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

    VS Code 扩展

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

    从 VS Code 市场安装

    该扩展提供：

    • 翻译键的自动补全。
    • 实时错误检测，用于发现缺失的翻译。
    • 内联预览已翻译的内容。
    • 快速操作，轻松创建和更新翻译。 有关如何使用该扩展的更多详细信息，请参阅Intlayer VS Code 扩展文档。

    深入了解

    • 可视化编辑器：使用Intlayer 可视化编辑器以可视化方式管理翻译。
    • CMS 集成：您还可以将字典内容外部化并从CMS中获取。
    • CLI 命令：探索Intlayer CLI以执行诸如提取翻译或检查缺失键等任务。
    Adonis
    JSON