字典

概述

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

什么是字典？

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

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

字典 vs <T> 组件

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

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

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

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

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

我们的建议

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

如何使用字典

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

步骤 1：创建字典

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

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

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

export default dictionary;

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

withGTConfig() 函数将自动获取项目根目录或 src 目录中的字典文件。

步骤 2：引用字典

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

import { useTranslations } from 'gt-next';

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

import { getTranslations } from 'gt-next/server';

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

为其他语言加载字典

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

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

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

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

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

使用字典

变量

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

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

import { useTranslations } from 'gt-next';

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

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

gt-next 中的字典字符串支持 ICU 消息格式，这也允许您格式化变量。

前缀

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

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

import { useTranslations } from 'gt-next';

export default 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 流水线中或作为构建脚本的一部分。

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

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

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

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

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

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

注意事项

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

后续步骤

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