# node: エラー処理とフォールバック
URL: https://generaltranslation.com/ja/docs/node/guides/error-handling.mdx
---
title: エラー処理とフォールバック
description: 訳文が利用できない場合に何が起こるのか、またその対処方法
---

## デフォルトのフォールバック動作

翻訳を利用できない場合 — ロケールがサポートされていない、翻訳ファイルが見つからない、または CDN に接続できない場合など — `gt-node` は `defaultLocale` の原文の文字列を返します。翻訳がなくても、アプリがクラッシュすることはありません。

```js
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  // スペイン語の翻訳が利用できない場合、英語の原文を返す
  res.json({ message: gt('Hello, world!') });
});
```

<Callout>
  このフォールバックは自動です。訳文が見つからない場合でも、翻訳呼び出しを `try/catch` で囲む必要はありません。
</Callout>


## 未設定のロケール

`locales` に設定されていないロケールへのリクエストが来た場合、翻訳関数は `defaultLocale` にフォールバックします。

```js
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'], // 日本語は含まれていない
});

// Accept-Language: ja のリクエスト
// gt('Hello!') → 'Hello!' を返す（英語へのフォールバック）
```

新しいロケールに対応するには、`locales` 配列に追加し、訳文を再生成します:

```bash
npx gt translate
```


## 利用可能なロケールの確認

[`getLocales()`](/docs/node/api/get-locales) と [`getDefaultLocale()`](/docs/node/api/get-default-locale) を使うと、runtime で利用可能なロケールを確認できます。

```js
import { getLocales, getDefaultLocale } from 'gt-node';

app.get('/api/locales', (req, res) => {
  res.json({
    supported: getLocales(),
    default: getDefaultLocale(),
  });
});
```


## API レスポンスで翻訳を扱う

API を構築する際は、コンテンツがフォールバック言語であることを明示したい場合があります。

```js
import { getGT, getLocale, getDefaultLocale } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  const locale = getLocale();
  const defaultLocale = getDefaultLocale();

  res.json({
    message: gt('Hello, world!'),
    locale,
    isFallback: locale !== defaultLocale,
  });
});
```


## 翻訳のデバッグ

### 現在アクティブなロケールを確認する

```js
import { getLocale } from 'gt-node';

app.use((req, res, next) => {
  console.log(`[i18n] Request locale: ${getLocale()}`);
  next();
});
```


### 訳文が読み込まれているか確認する

開発では、`gt-node` は API 経由で on-demand に翻訳します。訳文が読み込まれていないように見える場合は、次を確認してください。

1. `GT_API_KEY` と `GT_PROJECT_ID` が設定されていることを確認する
2. ロケールが `locales` 配列に含まれていることを確認する
3. サーバーログにエラーがないか確認する

### 本番環境チェックリスト

デプロイ前に、以下を確認してください。

* [ ] `npx gt translate` が build script で正常に実行される
* [ ] すべてのターゲットロケールが `gt.config.json` に含まれている
* [ ] `GT_PROJECT_ID` が本番環境に設定されている
* [ ] `GT_API_KEY` が本番環境に設定されている (`npx gt translate` 用) 

<Callout type="warn">
  開発では、翻訳は on-demand で行われるため、遅くなることがあります。本番環境では、必ず `npx gt translate` を使って翻訳を事前生成してください。詳しくは [CLI docs](/docs/cli/translate) を参照してください。
</Callout>

## 次のステップ

* [文字列翻訳パターン](/docs/node/guides/strings) — 2 つの翻訳方法
* [ローカル翻訳の保存](/docs/node/guides/local-tx) — オフライン利用のために翻訳をバンドルする
* [`getLocale` API リファレンス](/docs/node/api/get-locale)