# gt-node: General Translation Node.js SDK: 快速开始
URL: https://generaltranslation.com/zh/docs/node/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 安装 General Translation 的 `gt-node` 库，并翻译你的第一个 Node.js 服务。

`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` 和 Express 作为依赖，并将 [`gt` CLI](/docs/cli/quickstart) 安装为开发依赖。

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

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

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

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

*注意：下面的服务器代码使用 ES module `import` 语法。请在你的 `package.json` 中设置 `"type": "module"`，以便 Node.js 运行它。*

### 2. 初始化库

将项目 ID 和开发 API 密钥提供给 Node.js 进程：

```bash
export GT_PROJECT_ID="your-project-id"
export GT_DEV_API_KEY="gtx-dev-..."
```

在应用启动时、处理请求之前，调用一次 [`initializeGT`](/docs/node/reference/functions/initialize-gt)。直接传入你的 locales。省略凭据字段时，`gt-node` 会从环境变量中读取 `GT_PROJECT_ID`、`GT_API_KEY` 和 `GT_DEV_API_KEY`；不会自动读取 `gt.config.json`。

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

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
});
```

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

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

```js 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. 翻译字符串

在 处理函数 中，先 await [`getGT`](/docs/node/reference/functions/get-gt)，获取与请求区域设置对应的翻译函数，然后再翻译字符串。通过 ICU 占位符插入变量值。

```js 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' }) });
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));
```

### 5. 运行并验证

将步骤 2–4 中的代码片段合并到一个 `server.js` 文件中，然后启动服务器。在生成翻译之前，处理函数会返回你的源字符串，这表明服务已正确配置。

```bash
node server.js
```

在另一个终端中，发送请求：

```bash
curl http://localhost:3000/api/greeting
```

```json title="Output"
{"message":"Hello, Alice!"}
```

### 6. 生成翻译

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

```bash
npx gt translate
```

*注意：[`gt translate`](/docs/cli/reference/commands/translate) 会读取 `gt.config.json`，并且需要项目 ID 和 API 密钥。请先运行 [`npx gt init`](/docs/cli/reference/commands/init) 以创建它们。*

 (有关何时使用 [`getGT`](/docs/node/reference/functions/get-gt)、[`msg`](/docs/node/reference/functions/msg) 和 [`tx`](/docs/node/reference/functions/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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.