接收有关即将发布的Intlayer的通知
    Creation:2024-03-07Last update:2025-09-30

    如何使用 Intlayer 制作多语言(i18n)组件

    本指南展示了在两种常见环境中制作多语言 UI 组件的最简步骤:

    • React(Vite/单页应用)
    • Next.js(应用路由)

    您将首先声明内容,然后在组件中获取内容。

    1) 声明您的内容(适用于 React 和 Next.js)

    在组件附近创建一个内容声明文件。这可以让翻译内容靠近使用位置,并且支持类型安全。

    component.content.ts
    import { t, type Dictionary } from "intlayer";const componentContent = {  key: "component-example",  content: {    title: t({      en: "Hello",      fr: "Bonjour",      es: "Hola",    }),    description: t({      en: "A multilingual React component",      fr: "Un composant React multilingue",      es: "Un componente React multilingüe",    }),  },} satisfies Dictionary;export default componentContent;

    如果您更喜欢配置文件,也支持 JSON 格式。

    component.content.json
    {  "$schema": "https://intlayer.org/schema.json",  "key": "component-example",  "content": {    "title": {      "nodeType": "translation",      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }    },    "description": {      "nodeType": "translation",      "translation": {        "en": "一个多语言的 React 组件",        "fr": "Un composant React multilingue",        "es": "Un componente React multilingüe"      }    }  }}

    2) 获取您的内容

    情况 A — React 应用 (Vite/SPA)

    默认方法:使用 useIntlayer 通过键来获取内容。这使组件保持简洁且类型安全。

    ComponentExample.tsx
    import { useIntlayer } from "react-intlayer";export function ComponentExample() {  const content = useIntlayer("component-example");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>    </div>  );}

    服务器端渲染或在提供者外部使用时:使用 react-intlayer/server,并在需要时传入明确的 locale

    ServerRenderedExample.tsx
    import { useIntlayer } from "react-intlayer/server";export function ServerRenderedExample({ locale }: { locale: string }) {  const content = useIntlayer("component-example", locale);  return (    <>      <h1>{content.title}</h1>      <p>{content.description}</p>    </>  );}

    另一种方式:如果你更喜欢在调用处组织结构,可以使用 useDictionary 读取整个声明的对象。

    ComponentWithDictionary.tsx
    import { useDictionary } from "react-intlayer";import componentContent from "./component.content";export function ComponentWithDictionary() {  const { title, description } = useDictionary(componentContent);  return (    <div>      <h1>{title}</h1>      <p>{description}</p>    </div>  );}

    方案 B — Next.js(App 路由)

    优先使用服务器组件以确保数据安全和性能。在服务器文件中使用来自 next-intlayer/serveruseIntlayer,在客户端组件中使用来自 next-intlayeruseIntlayer

    app/[locale]/example/ServerComponent.tsx
    import { useIntlayer } from "next-intlayer/server";export default function ServerComponent() {  const content = useIntlayer("component-example");  return (    <>      <h1>{content.title}</h1>      <p>{content.description}</p>    </>  );}
    app/[locale]/example/ClientComponent.tsx
    "use client";import { useIntlayer } from "next-intlayer";export function ClientComponent() {  const content = useIntlayer("component-example");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>    </div>  );}

    提示:对于页面元数据和 SEO,您还可以使用 getIntlayer 获取内容,并通过 getMultilingualUrls 生成多语言 URL。

    为什么 Intlayer 的组件方法是最佳选择

    • 内容共置:内容声明与组件紧密相邻,减少偏差并提升设计系统中的复用性。
    • 类型安全:键和值结构均为强类型;缺失的翻译会在构建时而非运行时暴露。
    • 服务器优先:原生支持服务器组件,提升安全性和性能;客户端钩子依然保持良好的使用体验。
    • 摇树优化:仅打包组件实际使用的内容,保持大型应用的负载体积小。
    • 开发体验与工具:内置中间件、SEO助手,以及可选的可视化编辑器/AI翻译,简化日常工作流程。

    请参阅针对 Next.js 的对比和模式总结:https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer

    相关指南和参考资料

    这些页面包含端到端的设置、提供者、路由和 SEO 辅助工具。

    接收有关即将发布的Intlayer的通知