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

请参阅 GitHub 上的应用模板。

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

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

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

完整的山猫覆盖

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

</Accordion>

捆绑尺寸

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

</Accordion>

可维护性

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

人工智能代理

自动化

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

</Accordion>

表现

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

无需开发即可扩展

</AccordionGroup>

1. 1

   安装依赖

   从你的 Lynx 项目中，安装以下包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive
   

   --interactive 标志是可选的。如果你是 AI 代理，请使用 intlayer-cli init。

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer react-intlayer lynx-intlayer
   

   Packages

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

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

   • lynx-intlayer
     Lynx 集成，提供用于将 Intlayer 与 Lynx bundler 集成的插件。

   ---

2. 2

   创建 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 配置文档。
3. 3

   将 Intlayer 插件添加到 Lynx bundler

   要在 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(),
     ],
   });
   

4. 4

   添加 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();
   }
   

5. 5

   声明您的内容

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

   • .content.json
   • .content.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • 等等

   示例：

   src/app.content.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "React",
       subtitle: t({
         zh: "在 Lynx 上",
         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 的内容文档。

   ---

6. 6

   在您的组件中使用 Intlayer

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

   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(() => {
       "background only";
       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>
     );
   };
   

   在基于字符串的 props 中使用 content.someKey 时（例如，按钮的 title 或 Text 组件的 children），调用 content.someKey.value 来获取实际字符串。

   ---

7. 7

   更改应用语言环境

   可选

   要从您的组件中切换语言环境，您可以使用 useLocale hook 的 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），以改进自动补全并捕获翻译错误：

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

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

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

Git 配置

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

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

VS Code 扩展

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

从 VS Code 市场安装

该扩展提供：

该扩展提供：

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

深入了解

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