# node: 文字列翻訳のパターン
URL: https://generaltranslation.com/ja/docs/node/guides/strings.mdx
---
title: 文字列翻訳のパターン
description: Node.js で文字列を翻訳する 2 つの方法 — インラインと事前登録済み
---

`gt-node` で文字列を翻訳する方法は 3 つあります。

1. **`getGT()` を使うインライン方式** — リクエストハンドラー内で文字列を直接翻訳します (build-time) 
2. **`msg()` / `getMessages()` を使う事前登録済み方式** — モジュールスコープで文字列を定義し、runtime で解決します (build-time) 
3. **`tx()` を使う オンデマンド 方式** — runtime で文字列を翻訳します。これには、build-time 時点では不明なコンテンツも含まれます

## `getGT()` を使ったインライン翻訳

文字列を 1 か所でしか使わない場合や、コンテンツがリクエストごとのデータに依存する場合は、[`getGT()`](/docs/node/api/get-gt) を使用します。

```js title="routes/greeting.js"
import { getGT } from 'gt-node';

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


### 変数の補間

変数は、`{name}` プレースホルダーを使って第2引数に渡します。

```js
const gt = await getGT();

gt('Welcome, {name}!', { name: user.displayName });
gt('You have {count} new messages.', { count: unreadCount });
gt('{city} weather: {temp}°F', { city: 'Tokyo', temp: 72 });
```


## `msg()` / `getMessages()` を使った事前登録済みの文字列

[`msg()`](/docs/node/api/get-messages) を使って、モジュールスコープ、つまりリクエストハンドラーの外側で文字列を登録します。次に、ハンドラー内で [`getMessages()`](/docs/node/api/get-messages) を使い、現在のロケールに応じた文字列として解決します。

```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.');
export const UNAUTHORIZED = msg('You must be logged in.');
```

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

app.get('/api/greeting', 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) });
});
```

このアプローチが最適なのは、次のような場合です。

* 同じ文字列を複数のハンドラーで使い回す
* 文字列が共有定数 (エラーメッセージ、ラベル、列挙型) として定義されている
* レビューしやすいように、翻訳対象の文字列をすべて1つのファイルにまとめたい


## `tx()` を使った オンデマンド 翻訳

コンテンツがビルド時点では不明な場合、たとえば事前に翻訳できないユーザー生成コンテンツや動的データには、[`tx()`](/docs/node/api/strings/tx) を使用します。

```js title="routes/translate.js"
import { tx } from 'gt-node';

app.post('/api/translate', async (req, res) => {
  const translated = await tx(req.body.text);
  res.json({ translated });
});
```

`tx` は非同期で、ネットワークリクエスト経由でオンデマンドに翻訳を実行するため、build-time のアプローチより低速です。このユースケースに `getGT()` または `msg()` では対応できない場合にのみ使用してください。

## どちらをいつ使うか

| パターン                      | 適した用途                                     |
| ------------------------- | ----------------------------------------- |
| `getGT()`                 | 単発の文字列、リクエストごとのコンテンツ、1 つのハンドラー内でしか使わない文字列 |
| `msg()` / `getMessages()` | 共有定数、エラーメッセージ、列挙型のラベル、文字列の一元管理            |
| `tx()`                    | build 時点では不明な動的コンテンツまたはユーザー生成コンテンツ        |

<Callout>
  どちらのアプローチでも生成される訳文は同じです。違いはコードの構成だけなので、プロジェクトの構造に合うほうを選んでください。
</Callout>

## 曖昧さを解消するための`$context`の使用

曖昧な文字列は、不正確な訳文の原因になります。翻訳の手がかりとして`$context`を追加します。

```js
// インライン
const gt = await getGT();
gt('Apple', { $context: 'テクノロジー企業' });
gt('Spring', { $context: '季節（バネではなく）' });

// 事前登録済み
const APPLE = msg('Apple', { $context: '果物' });
const SPRING = msg('Spring', { $context: '金属製のバネ' });
```


## 完全な例

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

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

// 共有文字列を事前登録する
const ERRORS = {
  notFound: msg('Resource not found.'),
  unauthorized: msg('You must be logged in.'),
  forbidden: msg('You do not have permission to access this resource.'),
};

const app = express();

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

// インライン翻訳
app.get('/api/dashboard', async (req, res) => {
  const gt = await getGT();
  res.json({
    title: gt('Dashboard'),
    subtitle: gt('Welcome back, {name}!', { name: req.user.name }),
  });
});

// 事前登録済みメッセージ
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(ERRORS.notFound) });
});

app.listen(3000);
```


## 次のステップ

* [`getGT` API リファレンス](/docs/node/api/get-gt)
* [`msg` と `getMessages` API リファレンス](/docs/node/api/get-messages)
* [`tx` API リファレンス](/docs/node/api/strings/tx) — runtime 翻訳
* [ロケール検出とミドルウェア](/docs/node/guides/middleware) — ロケールのコンテキストの仕組み