字典参考

概述

在本参考指南中，我们将向您介绍字典模式。 请随时根据需要浏览本页面。 我们将涵盖以下内容：

• 什么是字典？
• 如何使用字典
• 加载其他语言的字典
• 使用字典
• 生产环境考虑因素

什么是字典？

通用翻译允许可翻译内容存储在字典文件中。 字典是一个嵌套对象，带有字符串值，可用于存储可翻译内容。 然后使用这个字典文件（.ts、.js 或 .json）来生成翻译。

字典可以单独使用，也可以与 <T> 组件结合使用。

字典与 <T> 组件的比较

字典模式相比 <T> 组件有几个优势：

1. 集中存储：字典将所有可翻译内容存储在单个文件中，使其更容易管理和更新。
2. 历史先例：字典模式是行业中常见的设计模式，被许多其他库使用。

同时，它也有一些缺点：

1. 复杂性：字典的设置和使用比 <T> 组件更复杂。
2. 可读性：字典比 <T> 组件可读性差，因为内容不是内联的。
3. 可维护性：字典比 <T> 组件更难维护，因为内容不是内联的，而是单独存储的。这使得调试和维护翻译变得更加困难。

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

我们的建议

我们推荐使用 <T> 组件，因为它的简单性，特别是如果你是国际化（i18n）的新手。 我们提供字典支持是为了那些因过去经验而偏好这种设计模式的人，或者为了更容易与现有代码库集成。

如何使用字典

在本节中，我们将向您展示如何在React应用程序中设置基础的字典实现。 我们将通过以下步骤进行：

步骤1：创建字典

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

在您的dictionary.js文件中添加以下内容：

const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}
 
export default dictionary;

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

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

import dictionary from "./dictionary.js";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

步骤2：引用字典

您可以使用useDict()钩子访问字典条目。 只需使用d()函数通过标识符访问字典条目。

import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')} // [!code highlight]
    </div>
  );
}

加载其他语言的字典

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

通用翻译（General Translation）会自动为其他语言生成字典，并使用loadTranslations函数加载它们。

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

当使用useDict()钩子或getDict()函数时，gt-react将自动加载请求的区域设置对应的字典。

查看API参考获取更多信息。

使用字典

变量

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

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

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

在 the DictionaryTranslationOptions type 中阅读更多关于将变量添加到字典的信息。

前缀

此外，使用 useDict()，您可以向函数传递一个前缀，以指定字典中的共享路径。 如果您在字典中有一个共享路径，并希望在多个组件中使用，这将非常有用。

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

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // 所有翻译路径如 'hello' 将被前缀为 'greetings'
  const d = useDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

生产注意事项

部署到生产环境

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

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

就是这样！您已成功将您的应用程序翻译成法语、西班牙语和日语。

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

行为：开发与生产

在开发中，d() 函数将按需翻译字典条目。这意味着当组件被渲染时，它将立即执行翻译。我们这样做是为了方便，使得与其他语言的开发更容易。

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

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

注意事项

• 字典是 <T> 组件的替代方案。它们可以与 <T> 组件一起使用，也可以单独使用。
• 字典翻译在构建时发生，因此您必须将 translate 命令添加到您的构建过程中。
• 字典可以与前缀一起使用，以指定字典的子集。

下一步

• 了解 <T> 组件 以及如何在您的 React 应用程序中使用它。
• 了解如何通过我们的部署指南进行生产部署。