字典参考

概述

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

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

什么是字典？

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

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

字典与 `<T>` 组件的比较

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

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

同时，它也有一些缺点：

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

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

我们的建议

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

如何使用字典

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

创建字典

引用字典

步骤 1：创建字典

第一步是创建一个字典。这是一个包含所有您想要翻译内容的 dictionary.js（.ts 或 .json）文件。在您的 src/ 目录中创建字典。

dictionary.js <--- 在此处添加字典文件

middleware.js

next.config.js

如果您没有使用 src/ 文件夹，您也可以在 next.config.js 文件中指定字典的目录。

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

src/dictionary.js

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

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

src/dictionary.json

{
  "greetings": {
    "goodbye": "Goodbye, World!"
  }
}

步骤 2：引用字典

根据您尝试使用字典的上下文，有几种使用字典的方法。例如，如果您在客户端组件中，使用 useDict() 钩子，而对于服务器端组件，使用 await getDict()。

以下是如何在客户端组件中使用字典的示例：

"use client";
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
 
  const d = useDict(); // 在客户端，您使用 useDict 钩子
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

以下是如何在服务器端组件中访问翻译的示例：

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
 
  const d = await getDict(); // 在服务器端，您必须等待一个 promise
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

加载其他语言的字典

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

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

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

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

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

使用字典

变量

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

src/dictionary.js

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

src/components/MyComponent.js

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  const d = await getDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'World' }})}
      {d('greetings.goodbye', { variables: { name: 'World' }})}
    </div>
  );
}

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

前缀

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

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

src/components/MyComponent.js

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

使用 `<GTProvider>` 的子集

您还可以在 <GTProvider> 组件中指定一个前缀。这将把字典的一个子集传递给客户端，因此不必加载整个字典。这仅适用于客户端组件。

layout.js

import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider id="nested.dictionary.key"> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}

在引用字典中的键时，您仍然需要指定完整路径。

"use client";
 
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('nested.dictionary.key.greeting')} // [!code highlight]
    </div>
  );
}

生产环境考虑因素

部署到生产环境

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

package.json

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

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

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

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

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

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

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

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

注意事项

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

下一步

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

字典参考

在本页面