字典

概述

在本指南中，我们将为你介绍词典的相关内容。你可以根据需要自由跳转浏览本页内容。我们将涵盖以下内容：

什么是词典？

如何使用词典

加载其他语言的词典

使用词典

生产环境注意事项

注意： 如果你正在使用 gt-react，我们不建议使用词典。请改为查看 <T> 组件。

本指南适用于已经熟悉词典并希望了解如何与 gt-react 搭配使用，或是正在尝试从其他 i18n 库迁移到 gt-react 的用户。

什么是字典？

字典是一个嵌套对象，包含字符串值，可用于存储可翻译的内容。它们可以存储在 .ts、.js 或 .json 文件中。

gt-react 允许你单独使用字典，或与 <T> 组件结合使用。

字典 vs `<T>` 组件

字典模式相比 <T> 组件有一些优势：

集中存储：字典将所有可翻译内容集中存储在一个文件中。
历史先例：字典模式是业界常见的设计模式，许多其他 i18n 库也采用了这种方式。

同时，它也有几个主要的劣势：

复杂性：字典的设置和使用比 <T> 组件更复杂。
可读性：由于内容不是内联的，字典的可读性不如 <T> 组件。
可维护性：由于内容不是内联的，而是单独存储，字典的维护比 <T> 组件更困难。这使得维护和更新翻译变得更加困难。
可调试性：出于同样的原因，字典的调试也比 <T> 组件更难。在调试 React 组件时，你需要追踪字典中的内容被使用的位置，而不能直接在代码库中搜索。

我们的库同时支持这两种设计模式，并且它们并不互斥。你可以将字典与 <T> 组件一起使用。

我们的建议

我们推荐使用 <T> 组件，因为它简单易用，尤其适合刚接触国际化（i18n）的人。对于那些习惯于这种设计模式或需要与现有代码库集成的用户，我们也提供了字典支持。

如何使用字典

在本节中，我们将向您展示如何在 React 应用程序中设置一个基本的字典实现。我们将逐步完成以下步骤：

创建字典

引用字典

步骤 1：创建字典

第一步是创建一个字典。这是一个包含您想要翻译的所有内容的 dictionary.[js|ts|json] 文件。

将以下内容添加到您的 dictionary 文件中：

src/dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Hello, world!'
  },
}

export default dictionary;

您也可以使用 dictionary.json 文件来存储您的字典。如果您正在从其他库迁移或者更喜欢使用 JSON 文件，这会很有用。以下是 dictionary.json 文件的示例：

src/dictionary.json

{
  "greetings": {
    "hello": "Hello, world!"
  }
}

然后将其传递给您的 <GTProvider> 组件：

index.js

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

步骤 2：引用字典

您可以使用 useTranslations() hook 访问字典条目。只需使用该 hook 返回的函数通过键来访问字典条目。

src/components/MyComponent.tsx

import { useTranslations } from 'gt-react';

export default function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

为其他语言加载字典

默认情况下，开发者只为默认语言提供字典。

General Translation 会自动为其他语言生成字典，并通过 loadTranslations 函数加载它们。

但是，如果您正在从另一个 i18n 库迁移或已经拥有其他语言的字典，您可以将它们传递给 loadDictionary 函数。

当使用 useTranslations() hook 或 getDict() 函数时，gt-react 会自动为请求的语言环境加载相应的字典。

有关更多信息，请参阅 API 参考。

使用字典

变量

您可以通过使用 {variable} 语法向字典中添加变量：

src/dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

src/components/MyComponent.tsx

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

在 DictionaryTranslationOptions 类型中了解更多关于向字典添加变量的信息。

前缀

此外，使用 useTranslations() 时，您可以向函数传递一个前缀来指定字典中的共享路径。当您的字典中有一个想要在多个组件中使用的共享路径时，这非常有用。

src/dictionary.js

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, world!',
      goodbye: 'Goodbye, world!'
    },
  },
}
export default dictionary;

src/components/MyComponent.js

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  // 所有翻译路径（如 'hello'）都将以 'greetings.common.' 为前缀
  const d = useTranslations('greetings.common'); 

  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

生产环境注意事项

部署到生产环境

确保在部署到生产环境之前运行 translate 命令，这样所有翻译在运行时都可用。我们建议将其添加到您的 CD 流水线中或作为构建脚本的一部分。

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
  }
}

有关部署应用程序的更详细指南，请参考部署指南。有关该命令的更多信息，请参考 CLI 工具参考指南。

行为：开发环境 vs 生产环境

在开发环境中，useTranslations() hook 返回的函数将按需翻译字典条目。这意味着当组件渲染时，它会立即执行翻译。我们这样做是为了方便使用其他语言进行开发。

要启用此行为，只需在您的环境中添加一个开发 API 密钥。

在生产环境中，d() 函数将在构建时翻译内容。这意味着您必须在部署应用程序之前运行翻译命令。

提示： 如果您想在开发环境中模拟生产环境行为，只需在开发构建中使用生产 API 密钥。

注意事项

字典是 <T> 组件的另一种选择。它们可以与 <T> 组件一起使用，也可以单独使用。
字典翻译在构建时进行，因此你需要将 translate 命令添加到你的构建流程中。
字典可以与前缀一起使用，以指定字典的子集。

下一步

了解 <T> 组件以及如何在你的 React 应用中使用它。
通过我们的部署指南学习如何上线到生产环境。

字典

在本页面