# node: Node.js クイックスタート
URL: https://generaltranslation.com/ja/docs/node/tutorials/quickstart.mdx
---
title: Node.js クイックスタート
description: 10分以内で Node.js サーバーに多言語対応を追加
---
このガイドを終えるまでに、Node.js サーバーはインライン文字列または事前登録した文字列を使って、リクエストの言語に応じた翻訳済みコンテンツを返せるようになります。
**前提条件:**
* Node.js サーバー (Express、Fastify など)
* Node.js 18 以降
**自動セットアップを使いたい場合:** `npx gt@latest` を実行すると、[セットアップウィザード](/docs/cli/init) ですべて設定できます。このガイドでは手動でのセットアップを扱います。
***
## ステップ 1: パッケージをインストールする
`gt-node` はサーバー側の翻訳を担うライブラリです。`gt` は翻訳を本番環境向けに準備する CLI ツールです。
```bash
npm i gt-node
npm i -D gt
```
```bash
yarn add gt-node
yarn add --dev gt
```
```bash
bun add gt-node
bun add --dev gt
```
```bash
pnpm add gt-node
pnpm add --save-dev gt
```
***
## ステップ 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
```
`GT_API_KEY` は絶対に公開したり、ソース管理にコミットしたりしないでください。
はい。API キーがなくても、`gt-node` は標準的な i18n ライブラリとして動作します。開発時のオンデマンド翻訳は利用できませんが、次のことは引き続き行えます。
* 独自の翻訳ファイルを手動で用意する
* すべての翻訳関数 (`getGT`、`msg`、`getMessages` など) を使う
* `npx gt generate` を実行して翻訳ファイルのテンプレートを作成し、その後自分で翻訳する
***
## ステップ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
```
各言語で翻訳されたレスポンスが表示されるはずです。
開発環境では、翻訳はオンデマンドで実行されます。新しい言語を初めてリクエストした際は、短時間の遅延が発生することがあります。本番環境では、翻訳は事前生成されるため、即座に読み込まれます。
***
## ステップ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 && "
}
}
```
ホスティングプロバイダーで、**本番環境** 用の環境変数を設定します。
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
`GT_API_KEY` は絶対に公開しないでください。
以上です。これでサーバーは多言語対応になりました。🎉
***
## トラブルシューティング
これは想定どおりの動作です。開発環境では、翻訳はオンデマンドで行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は**本番環境では発生しません**。すべての翻訳は `npx gt translate` によって事前生成されます。
テキストが曖昧だと、翻訳が不正確になることがあります。たとえば、"apple" は果物を意味する場合もあれば、企業を意味する場合もあります。意味を明確にするには、`$context` オプションを追加してください。
```js
gt('Apple', { $context: 'the technology company' });
```
`getGT()` と `msg()` はどちらも `$context` オプションをサポートしています。
***
## 次のステップ
* [**`initializeGT`**](/docs/node/api/initialize-gt) — 設定オプション一覧
* [**`withGT`**](/docs/node/api/with-gt) — リクエストのロケールコンテキスト
* [**`getGT`**](/docs/node/api/get-gt) — インライン文字列の翻訳
* [**`msg` & `getMessages`**](/docs/node/api/get-messages) — 事前登録済みメッセージの翻訳
* [**CLI**](/docs/cli/translate) — 翻訳ワークフローのリファレンス