# node: Node.js 快速入门
URL: https://generaltranslation.com/zh/docs/node/tutorials/quickstart.mdx
---
title: Node.js 快速入门
description: 在 10 分钟内为你的 Node.js 服务器添加多语言支持
---

完成本指南后，你的 Node.js 服务器将能够根据请求的语言，使用内联字符串或预注册字符串返回翻译内容。

**前提条件：**

* 一个 Node.js 服务器 (Express、Fastify 或类似框架) 
* Node.js 18+

<Callout type="info">
  **想自动セットアップ？** 运行 `npx gt@latest`，通过[セットアップ向导](/docs/cli/init)完成所有配置。本指南介绍手动セットアップ。
</Callout>

***

## 第 1 步：安装软件包

`gt-node` 是为你的服务器提供翻译能力的库。`gt` 是用于为生产环境准备翻译的 CLI 工具。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-node
    npm i -D gt
    ```
  </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 步：创建翻译配置文件

在项目根目录下创建一个 **`gt.config.json`** 文件。该文件用于告诉库你支持哪些语言：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"]
}
```

* **`defaultLocale`** — 你的服务器端字符串所使用的语言。
* **`locales`** — 你想翻译成的语言。可从[支持的区域设置列表](/docs/platform/supported-locales)中任选。

***


## 第 3 步：初始化 General Translation

在服务器入口文件的顶部调用一次 **`initializeGT`**，并且要在使用任何翻译函数之前调用：

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

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

这会使用您支持的语言和项目凭据对该库进行配置。

***


## 第 4 步：为每个请求设置区域设置上下文

每个请求都需要知道要使用哪种语言。使用 **`withGT`** 封装请求处理程序——它会使用异步本地存储，因此翻译函数会自动读取正确的区域设置：

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

app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});
```

***


## 第 5 步：翻译内联字符串

如需直接在请求处理程序中翻译字符串，请使用 **`getGT`**：

```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, world!'),
    welcome: gt('Welcome, {name}!', { name: 'Alice' }),
  });
});
```

`getGT` 返回一个以当前请求的区域设置为作用域的翻译函数。

***


## 第 6 步：预注册常量字符串 (可选) 

对于在请求处理程序之外定义的字符串 (例如错误消息、枚举标签或常量) ，请使用 **`msg`** 在模块作用域中注册它们，然后使用 **`getMessages`** 在 runtime 解析这些翻译：

```js title="messages.js"
import { msg } from 'gt-node';

export const GREETING = msg('Hello, world!');
export const WELCOME = msg('Welcome, {name}!');
export const NOT_FOUND = msg('Resource not found.');
```

```js title="handler.js"
import { getMessages } from 'gt-node';
import { GREETING, WELCOME, NOT_FOUND } from './messages.js';

app.get('/api/status', async (req, res) => {
  const m = await getMessages();
  res.json({
    greeting: m(GREETING),
    welcome: m(WELCOME, { name: 'Alice' }),
  });
});

app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});
```

当多个处理程序会复用同一组字符串时，这种模式很有用。

***


## 第 7 步：设置环境变量 (可选) 

如果你想在开发环境中看到翻译效果，就需要 General Translation 提供的 API 密钥。它们会启用**按需翻译**——这样你在开发过程中，服务器就能实时翻译内容。

创建一个 **`.env`** 文件：

```bash title=".env"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

前往 [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) 免费领取密钥，或运行：

```bash
npx gt auth
```

<Callout type="warn">
  切勿公开暴露 `GT_API_KEY`，也不要将其提交到源代码版本控制系统中。
</Callout>

<Accordions>
  <Accordion title="不使用 API 密钥也能使用 gt-node 吗？">
    可以。不使用 API 密钥时，`gt-node` 会作为标准 i18n 库运行。你无法在开发环境中使用按需翻译，但仍然可以：

    * 手动提供自己的翻译文件
    * 使用所有翻译函数 (`getGT`、`msg`、`getMessages` 等) 
    * 运行 `npx gt generate` 生成翻译文件模板，然后自行翻译
  </Accordion>
</Accordions>

***


## 第 8 步：查看效果

启动你的 服务器，并使用不同的 `Accept-Language` 标头进行测试：

```bash
# 默认（英语）
curl http://localhost:3000/api/greeting

# 西班牙语
curl -H "Accept-Language: es" http://localhost:3000/api/greeting

# 法语
curl -H "Accept-Language: fr" http://localhost:3000/api/greeting
```

你应该会看到每种语言对应的翻译结果。

<Callout type="info">
  在开发环境中，翻译按需生成——首次请求某种新语言时，可能会有短暂延迟。在生产环境中，翻译会预先生成并立即加载。
</Callout>

***


## 第 9 步：完整示例

以下是一个整合了所有部分的完整 Express 服务器：

```js title="server.js"
import express from 'express';
import { initializeGT, withGT, getGT, msg, getMessages } from 'gt-node';

// 在其他所有操作之前初始化 GT
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});

// 预注册常量字符串
const NOT_FOUND = msg('Resource not found.');

const app = express();

// 为每个请求设置区域设置上下文
app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});

// 内联翻译
app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, world!') });
});

// 预注册消息翻译
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

***


## 第 10 步：部署到生产环境

在生产环境中，翻译会在构建阶段预先生成 (不会发起实时 API 调用) 。将 `translate` 命令添加到构建脚本中：

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

在你的托管平台中设置 **生产环境** 环境变量：

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  切勿公开泄露你的 `GT_API_KEY`。
</Callout>

就是这样——你的服务器现在已经支持多语言了。🎉

***


## 故障排查

<Accordions>
  <Accordion title="开发环境中翻译较慢">
    这是正常现象。在开发环境中，翻译会按需进行 (你的内容会通过 API 实时翻译) 。**生产环境中不会有这种延迟**——所有翻译都会由 `npx gt translate` 预先生成。
  </Accordion>

  <Accordion title="部分翻译不准确">
    有歧义的文本可能会导致翻译不准确。例如，&quot;apple&quot; 既可能指水果，也可能指公司。添加 `$context` 选项可帮助系统判断：

    ```js
    gt('Apple', { $context: 'the technology company' });
    ```

    `getGT()` 和 `msg()` 都支持 `$context` 选项。
  </Accordion>
</Accordions>

***

## 下一步

* [**`initializeGT`**](/docs/node/api/initialize-gt) — 完整配置选项
* [**`withGT`**](/docs/node/api/with-gt) — 请求的区域设置上下文
* [**`getGT`**](/docs/node/api/get-gt) — 内联字符串翻译
* [**`msg` &amp; `getMessages`**](/docs/node/api/get-messages) — 预注册消息翻译
* [**CLI**](/docs/cli/translate) — 翻译工作流参考