# General Translation Knowledge Base: react-i18next から gt-react へ移行するにはどうすればよいですか？
URL: https://generaltranslation.com/ja/kb/migrate-from-react-i18next.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: gt-react を react-i18next と並べてインストールし、ロケールのクッキーを1つ共有したうえで、t() のキーと `<Trans>` を使ったコンポーネントを、`<T>` と useGT によるインラインのテキストへ1つずつ移行します。移行したテキストは General Translation が JSX を文脈として翻訳し、チームはダッシュボードで修正できます。移行していないコンポーネントでは、レビュー済みの react-i18next の翻訳が引き続き使われます。
Category: 国際化
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

react-i18next は、言語と namespace ごとの JSON ファイルに記述した翻訳をレンダリングします。一方、gt-react はコンポーネント内にインラインで記述したテキストをレンダリングし、その翻訳は General Translation が [`npx gt translate`](/docs/cli/reference/commands/translate) で生成します。移行では、両方のライブラリを並行して動かしながら、`t('key')` による参照を、キーが指す原文にコンポーネント単位で置き換えていきます。

General Translation を使うために移行は必須ではありません。`gt` CLI は `package.json` 内の `i18next` を検出し、i18next の `{{variable}}` 構文を保持したまま JSON ファイルを翻訳します。キーの命名や言語ごとのファイルの手動同期をやめ、テキストをレンダリング元の JSX のそばに置きたい場合に移行を検討してください。

## react-i18next の API は gt-react のどれに対応しますか？

| react-i18next                                  | gt-react                                                                                                                                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `i18n.init({ lng, supportedLngs, resources })` | `gt.config.json` (`defaultLocale`、`locales`) と、エントリファイル内の [`initializeGTSPA`](/docs/react/reference/config#initialize-spa)                                                                              |
| `I18nextProvider` / `initReactI18next`         | シングルページアプリ (SPA) ではプロバイダーは不要です。サーバーでレンダリングされるアプリでは、[`initializeGT`](/docs/react/reference/config#initialize) と [`GTProvider`](/docs/react/reference/components/gt-provider) を使用します                      |
| `<Trans i18nKey="..." components={...}>`       | 実際の JSX を [`<T>`](/docs/react/reference/components/t) でラップし、リンクやマークアップはインラインで記述します                                                                                                                      |
| 文字列用の `t('key')`                               | 翻訳元文字列を渡す [`useGT`](/docs/react/reference/hooks/use-gt)、またはキーを引き続き使う場合は [`useTranslations`](/docs/react/reference/hooks/use-translations)                                                               |
| `{{name}}` による補間                               | JSX では [`<Var>`](/docs/react/reference/components/var)、文字列では `{name}`                                                                                                                                   |
| `count` を伴う `key_one` / `key_other`            | JSX では [`<Plural>`](/docs/react/reference/components/plural)、文字列では ICU の `{n, plural, ...}`                                                                                                             |
| `useTranslation('ns')` または `keyPrefix`         | `useTranslations('ns')` で参照をプレフィックス配下にスコープします                                                                                                                                                           |
| `{{val, number}}` などのフォーマッター                   | [`<Num>`](/docs/react/reference/components/num)、[`<Currency>`](/docs/react/reference/components/currency)、[`<DateTime>`](/docs/react/reference/components/datetime)                                     |
| `i18n.changeLanguage()` / `i18n.language`      | [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) / [`useLocale`](/docs/react/reference/hooks/use-locale)、または [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) コンポーネント |
| `i18next-browser-languagedetector`             | 組み込みで対応：`generaltranslation.locale` クッキーを優先し、次にブラウザの言語設定を参照します                                                                                                                                          |
| `fallbackLng`                                  | 翻訳が存在しない場合は原文がレンダリングされます                                                                                                                                                                                |

## ステップ1：react-i18next と併用して gt-react をインストールする

Vite または webpack のアプリの場合は [React SPA クイックスタート](/docs/react/react-spa-quickstart)、サーバーでレンダリングされるアプリの場合は [Reactクイックスタート](/docs/react/react-quickstart) に従ってください。SPA でのセットアップ手順は次のとおりです。

1. `gt-react` をインストールし、`gt` CLI を開発依存関係としてインストールします。
2. i18next の設定と同じソースロケールとターゲットロケールを指定して、`gt.config.json` を作成します。
3. [`loadTranslations`](/docs/react/reference/functions/load-translations) 関数を追加します。続いて、エントリファイルで [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) を呼び出し、翻訳の読み込みが完了してからアプリの残りの部分をインポートするようにします。
4. [`npx gt login`](/docs/cli/reference/commands/login) でサインインし、プロジェクトIDを設定します。

`i18n.init` と JSON ファイルはそのまま残してください。コンポーネントを移行するまでは、ユーザーから見た動作は何も変わりません。`gt.config.json` の `files` に i18next のファイルを指定している場合は、そのエントリを削除し、各文字列の翻訳を管理する仕組みが1つだけになるようにしてください。未移行のコンポーネントの翻訳は引き続き JSON で管理し、新規の文言や変更した文言は gt-react でインラインに記述します。

## ステップ 2: アクティブなロケールを1つに統一する

2つのライブラリを併用すると、ユーザーの言語の認識が食い違うことがあります。言語切り替え機能には gt-react を使用し、i18next が同じクッキーを読み取るように設定します:

```ts title="src/i18n.ts"
import i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    // ...既存のオプション
    detection: {
      order: ['cookie', 'navigator'],
      lookupCookie: 'generaltranslation.locale', // gt-react が書き込むクッキー
      caches: [],
    },
  });
```

既存の言語メニューを、gt-react の [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) か、[`useSetLocale`](/docs/react/reference/hooks/use-set-locale) を呼び出すコントロールに置き換えてください。SPA では、言語を切り替えるとクッキーが書き込まれてページが再読み込みされるため、どちらのライブラリも新しい言語で起動します。次のステップに進む前に、移行済みの画面と未移行の画面の間で正しく遷移できるかテストしてください。

## ステップ 3: コンポーネントを 1 つずつ移行する

JSON にあるソース言語のテキストをコンポーネントにコピーし、変数はそのまま変数として残します。変更前:

```json title="public/locales/en/translation.json"
{
  "inbox": "Hi {{name}}, <link>open your inbox</link>.",
  "messages_one": "You have {{count}} message",
  "messages_other": "You have {{count}} messages"
}
```

```tsx title="src/Inbox.tsx"
import { Trans, useTranslation } from 'react-i18next';

export function Inbox({ name, count }: { name: string; count: number }) {
  const { t } = useTranslation();
  return (
    <>
      <Trans i18nKey="inbox" values={{ name }} components={{ link: <a href="/inbox" /> }} />
      <p>{t('messages', { count })}</p>
    </>
  );
}
```

変更後：

```tsx title="src/Inbox.tsx"
import { T, Var, Plural, Num } from 'gt-react';

export function Inbox({ name, count }: { name: string; count: number }) {
  return (
    <T>
      Hi <Var>{name}</Var>, <a href="/inbox">open your inbox</a>.
      <p>
        <Plural
          n={count}
          singular={<>You have <Num>{count}</Num> message</>}
          plural={<>You have <Num>{count}</Num> messages</>}
        />
      </p>
    </T>
  );
}
```

リンクは番号付きのプレースホルダーに置き換えられず、実際の `<a>` 要素のまま残ります。General Translation はブロック全体を、その構造を文脈として活用しながら翻訳します。また、記述した `singular` と `plural` をもとに、ポーランド語の `few` や `many` のように各対象言語で必要な形を生成します。そのうえで、[`<Plural>`](/docs/react/reference/components/plural) が個数に応じて適切な形を選択します。

プレースホルダーやトーストなど、JSX 外の文字列には [`useGT`](/docs/react/reference/hooks/use-gt) を使用します。変数は単一の波括弧で囲みます。また、意味が曖昧な語には文脈を追加できます:

```tsx
import { useGT } from 'gt-react';

function Search({ count }: { count: number }) {
  const gt = useGT();
  return <input placeholder={gt('Search {count} projects', { count })} />;
}

// イベントハンドラ内で、翻訳者向けのヒントを添える例：
toast(gt('Saved {fileName}', { fileName, $context: 'toast after saving a file' }));
```

第1引数は静的な文字列でなければならず、テンプレートリテラルや文字列連結は使用できません。コンポーネントを一定数移行するたびに [`npx gt translate`](/docs/cli/reference/commands/translate) を実行し、すべてのロケールを確認してください。

## 既存の翻訳キーはそのまま使えますか？

はい。キーを gt-react の単一の[辞書](/docs/react/guides/translating-with-dictionaries)にまとめ、`useTranslation` を [`useTranslations`](/docs/react/reference/hooks/use-translations) に置き換えるだけです。キーを参照する呼び出しはそのまま使えます：

```tsx
// 変更前
import { useTranslation } from 'react-i18next';
const { t } = useTranslation();

// 変更後
import { useTranslations } from 'gt-react';
const t = useTranslations();

return <h1>{t('home.welcome', { name })}</h1>;
```

辞書エントリは ICU MessageFormat を使用するため、JSON には次の 3 つの変更が必要です。

* `{{name}}` は `{name}` に変更します。
* 複数形キーは 1 つのエントリにマージします：`"messages": "You have {count, plural, one {# message} other {# messages}}"`。
* namespace ごとのファイルは 1 つの `dictionary.json` にマージし、各 namespace をトップレベルのキーにします。`useTranslation('settings')` は `useTranslations('settings')` に置き換えます。

[`npx gt validate`](/docs/cli/reference/commands/validate) は、ICU として無効なエントリがあると警告を出します。エントリが見つからない場合にキーを返す i18next とは異なり、[`useTranslations`](/docs/react/reference/hooks/use-translations) は例外をスローします。id とエントリは常に同期させておいてください。

## 既存の翻訳はどうなりますか？

まだ移行していないコンポーネントでは、レビュー済みの react-i18next の翻訳が引き続きレンダリングされます。そのため、段階的に移行すれば、変更が及ぶのは手を加えた画面だけです。[`<T>`](/docs/react/reference/components/t)、[`useGT`](/docs/react/reference/hooks/use-gt)、または gt-react の辞書に移したテキストは、[`npx gt translate`](/docs/cli/reference/commands/translate) で新たに翻訳されます。その際、[`<T>`](/docs/react/reference/components/t) の JSX 構造と、追加した文脈が反映されます。[コンテキストグループ](/docs/platform/dashboard/guides/defining-context-for-translations)の用語集とカスタムプロンプトを使えば、用語やトーンを統一できます。翻訳後の文言は、レビュー担当者が[ダッシュボード](/docs/platform/dashboard/guides/reviewing-translations)で自由に修正できます。

レビュー済みの翻訳を一字一句そのまま維持する必要がある場合は、react-i18next を引き続き使用し、その JSON ファイルを General Translation で翻訳してください ([General Translation と i18next の比較](/kb/general-translation-vs-i18next)を参照) 。

## ステップ 4: react-i18next を削除する

`useTranslation`、`<Trans`、`i18next` を検索して何もヒットしなくなったら、`i18n.init` ファイル、JSON ファイル、言語検出器、そして `i18next` と `react-i18next` の依存関係を削除します。その後、[`npx gt translate`](/docs/cli/reference/commands/translate) をビルドまたは [CI](/kb/translations-in-ci) に組み込み、新しく追加したテキストもリリースのたびに翻訳済みの状態で公開されるようにします。

## よくある質問

### すべてを一度に移行する必要がありますか？

いいえ。両方のライブラリが同じロケールを参照していれば、同じページ内で併用してレンダリングできます。ルートや機能単位で 1 つずつ移行し、i18next を使用している箇所がすべてなくなった時点で i18next を削除してください。

### gt-react はサーバーサイドレンダリングをサポートしていますか？

はい。サーバーサイドレンダリングされた React アプリでは、[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) の代わりに [`initializeGT`](/docs/react/reference/config#initialize) と [`GTProvider`](/docs/react/reference/components/gt-provider) を使用します。詳しくは [Reactクイックスタート](/docs/react/react-quickstart) を、`gt-next` を使用している場合は [Next.js クイックスタート](/docs/react/nextjs-quickstart) を参照してください。

### gt-react は無料ですか？

gt-react は MIT ライセンスで提供されており、バンドルされた翻訳はアカウントなしでレンダリングできます。General Translation による翻訳の生成は[従量課金制](https://generaltranslation.com/pricing)です。

## 重要なポイント

* gt-react を react-i18next と併用し、i18next の言語検出器が `generaltranslation.locale` クッキーを参照するように設定したうえで、言語の切り替えは gt-react で行います。
* `<Trans>` とキーによる参照を、[`<T>`](/docs/react/reference/components/t) と [`useGT`](/docs/react/reference/hooks/use-gt) を使ったインラインのテキストに置き換えます。`{{var}}` は [`<Var>`](/docs/react/reference/components/var) または `{var}` に、複数形キーは `singular` と `plural` を指定した [`<Plural>`](/docs/react/reference/components/plural) に置き換わります。
* 移行していないコンポーネントでは、レビュー済みの翻訳がそのまま維持されます。移行したテキストは JSX を文脈として翻訳され、ダッシュボードでレビューされます。
* キーを使い続けたい場合は、JSON を 1 つの ICU 辞書に変換し、[`useTranslations`](/docs/react/reference/hooks/use-translations) を使用します。
* i18next はどこからも参照されなくなった時点で削除し、CI で [`npx gt translate`](/docs/cli/reference/commands/translate) を実行します。

## Related questions

- [i18next の代替：General Translation と i18next の比較](https://generaltranslation.com/ja/kb/general-translation-vs-i18next.mdx): テキストを React コンポーネント内にインラインで記述したまま、JSX 構造とプロダクトの文脈を活かして翻訳を生成したい場合は、General Translation を選びましょう。i18next を使い続けながら、General Translation で既存のカタログを翻訳することもできます。i18next はメッセージのレンダリングと複数形の選択を担いますが、翻訳の生成には別のサービスが必要です。
- [React アプリを翻訳するには？](https://generaltranslation.com/ja/kb/translate-react-app.mdx): React アプリを翻訳するには、まずコンポーネントを国際化してユーザーの言語でレンダリングできるようにし、次にすべての文字列をサポート対象の各言語に翻訳します。General Translation の gt-react は `<T>` コンポーネント内の JSX をインプレースで翻訳し、npx gt translate は言語ごとに 1 つのファイルを書き出します。
- [JSX の外にある文字列はどのように翻訳しますか？](https://generaltranslation.com/ja/kb/translate-strings-outside-jsx.mdx): プレースホルダーやモジュールスコープの定数など、JSX の子要素ではない文字列は、それぞれレンダリングされる場所で翻訳関数に渡します。General Translation の useGT フックはこの翻訳関数を返します。また、msg と useMessages を組み合わせれば、コンポーネントの外で定義された定数も翻訳できます。
- [React で複数形を扱うにはどうすればよいですか？](https://generaltranslation.com/ja/kb/how-to-handle-plurals-in-react.mdx): React で複数形を扱うには、各言語の複数形ごとに文を 1 つずつ用意し、その言語の複数形規則に従って選択します。英語の複数形は 2 種類ですが、ロシア語は 4 種類、アラビア語は 6 種類あるためです。gt-react と gt-next に含まれる General Translation の `<Plural>` コンポーネントに翻訳元の形を渡せば、各対象言語に必要な形は General Translation が生成します。
- [デプロイのたびに翻訳を最新の状態に保つにはどうすればよいですか？](https://generaltranslation.com/ja/kb/translations-in-ci.mdx): 本番環境のビルド前に、翻訳をパイプラインのステップとして毎回実行します。こうすることで、新しいテキストは追加されたデプロイと同時に翻訳済みの状態でリリースされます。General Translation の gt CLI では、CI シークレットとして保存したプロジェクトの APIキーとプロジェクトIDを使い、npx gt translate でこれを実現します。

## Previous and next questions

- Previous question: [next-intl から gt-next に移行するには？](https://generaltranslation.com/ja/kb/migrate-from-next-intl.mdx)
- Next question: [vue-i18n から gt-vue へ移行するにはどうすればよいですか？](https://generaltranslation.com/ja/kb/migrate-from-vue-i18n.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/ja/kb/sitemap.md) for every article.