# gt-node: General Translation Node.js SDK: 快速开始
URL: https://generaltranslation.com/zh/docs/node/quickstart.mdx
---

title: 快速开始
description: 安装 General Translation 的 `gt-node` 库，并翻译你的第一个 Node.js 服务。
related:
  links:
    - /docs/node/guides/translating-strings
    - /docs/node/guides/detecting-locale
    - /docs/node/guides/configuring
    - /docs/node/guides/storing-translations

---

`gt-node` 可在 Node.js 服务器和服务中翻译字符串。你只需初始化一次，为每个传入请求绑定区域设置，然后在处理函数中翻译字符串。

将 `gt-node` 用于 Express 或 Fastify API 等后端服务。React 应用请使用 [`gt-react`](/docs/react/react-quickstart)；Next.js 请使用 [`gt-next`](/docs/react/nextjs-quickstart)。

*注意：`gt-node` 需要 Node.js 18 或更高版本。按请求绑定区域设置时，会使用 `node:async_hooks` 中的 `AsyncLocalStorage`。*

## gt-node 的功能 [#what-it-does]

`gt-node` 为你提供：

* 通过 [`getGT`](/docs/node/reference/functions/get-gt) 实现**字符串翻译**，适用于 handler 内的局部字符串。
* 通过 [`msg`](/docs/node/reference/functions/msg) 和 [`getMessages`](/docs/node/reference/functions/get-messages) 使用**已注册消息**，适用于共享常量和错误。
* 通过 [`tx`](/docs/node/reference/functions/tx) 实现**运行时翻译**，适用于动态内容。
* 通过 [`withGT`](/docs/node/reference/functions/with-gt) 实现**按请求绑定区域设置**，并提供用于检测请求区域设置的辅助函数。

## 快速开始 [#quickstart]

安装该库并完成初始化，为每个请求绑定区域设置，然后翻译字符串。

### 1. 安装 `gt-node`

安装 `gt-node` 作为依赖，并将 [`gt` CLI](/docs/cli/quickstart) 安装为开发依赖。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-node && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-node && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-node && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-node && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. 初始化库

在应用启动时、处理请求之前，调用一次 [`initializeGT`](/docs/node/reference/functions/initialize-gt)。传入你的 locales 和凭据——`gt-node` 不会自动读取 `gt.config.json` 或环境变量。

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  projectId: process.env.GT_PROJECT_ID,
});
```

### 3. 绑定请求的区域设置

使用 `withGT` 包装每个请求，让翻译函数知道目标区域设置。使用 [`getRequestLocale`](/docs/node/reference/functions/get-request-locale) 从 `Accept-Language` header 中检测该区域设置。

```ts title="server.js"
import express from 'express';
import { withGT, getRequestLocale } from 'gt-node';

const app = express();
app.use((req, res, next) => withGT(getRequestLocale(req), () => next()));
```

### 4. 翻译字符串

在 handler 中，先 await `getGT`，获取与请求区域设置对应的翻译函数，然后再翻译字符串。通过 ICU 占位符插入变量值。

```ts title="server.js"
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, {name}!', { name: 'Alice' }) });
});
```

### 5. 生成翻译

在部署到生产环境之前运行 CLI，以确保翻译在运行时可用。

```bash
npx gt translate
```

有关何时使用 `getGT`、`msg` 和 `tx`，请参阅[翻译字符串](/docs/node/guides/translating-strings)；有关凭据和交付配置，请参阅[配置 gt-node](/docs/node/guides/configuring)。
## Next steps

- /docs/node/guides/translating-strings
- /docs/node/guides/detecting-locale
- /docs/node/guides/configuring
- /docs/node/guides/storing-translations