react-i18next

react-i18next スキル

react-i18next は、i18next を基盤として構築された、React／React Native 向けの標準的な国際化フレームワークです。このスキルでは、セットアップ、設定、すべての API、一般的なパターンを扱います。

重要なメンタルモデル：i18next は翻訳エンジンの中核（設定、複数形、補間、書式設定）です。react-i18next は、フック、HOC、レンダープロパティ、Trans コンポーネントを介して i18next をコンポーネントに接続する React バインディング層です。

インストール

npm install react-i18next i18next --save

# Common companion packages:
npm install i18next-http-backend i18next-browser-languagedetector --save

i18next の設定（i18n.js）

エントリーポイントと同じ場所に i18n.js を作成します。これが i18n セットアップの唯一の信頼できる情報源です。

最小限のセットアップ（リソースをインラインで指定）

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: {
        translation: {
          "welcome": "Welcome to our app"
        }
      },
      tr: {
        translation: {
          "welcome": "Uygulamamıza hoş geldiniz"
        }
      }
    },
    lng: 'en',              // default language
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false     // React already escapes by default
    }
  });

export default i18n;

本番環境向けのセットアップ（バックエンド＋言語検出）

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(Backend)              // loads translations from /public/locales/{lng}/{ns}.json
  .use(LanguageDetector)     // detects user language
  .use(initReactI18next)     // binds i18next to React
  .init({
    fallbackLng: 'en',
    debug: true,             // set false in production
    interpolation: {
      escapeValue: false
    },
    // react-specific options (all optional):
    // react: {
    //   bindI18n: 'languageChanged',
    //   bindI18nStore: '',
    //   transEmptyNodeValue: '',
    //   transSupportBasicHtmlNodes: true,
    //   transKeepBasicHtmlNodesFor: ['br', 'strong', 'i', 'p'],
    //   useSuspense: true,
    // }
  });

export default i18n;

次に、エントリーポイントでインポートします。

import './i18n';  // must be imported before App

翻訳ファイルの構成

i18next-http-backend を使用する場合は、ファイルを次の場所に配置します。

public/
  locales/
    en/
      translation.json    ← default namespace
      common.json          ← additional namespace
    tr/
      translation.json
      common.json

コア API

react-i18next には、翻訳にアクセスする方法が4つあります。用途に応じて選択してください。

方法	使用する場面
useTranslation フック	関数コンポーネント（推奨）
withTranslation HOC	クラスコンポーネント、または任意のコンポーネントをラップする場合
Translation レンダープロパティ	任意のコンポーネント型で t 関数が必要な場合
Trans コンポーネント	HTML／コンポーネントを含む JSX ツリーを翻訳する場合

1. useTranslation フック（主要 API）

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t, i18n } = useTranslation();
  return <h1>{t('welcome')}</h1>;
}

名前空間の読み込み：

const { t } = useTranslation('common');           // single namespace
const { t } = useTranslation(['ns1', 'ns2']);      // multiple (first = default)
t('key');                                          // looks up in default ns
t('key', { ns: 'ns2' });                          // explicit namespace

keyPrefix（react-i18next >= 11.12.0、i18next >= 20.6.0）：

// For deeply nested keys: { "very": { "deeply": { "nested": { "key": "value" }}}}
const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
t('key');  // → "value"

固定言語（react-i18next >= 12.3.1）：

const { t } = useTranslation('translation', { lng: 'de' });

Suspense を使用しない場合：

const { t, i18n, ready } = useTranslation('ns1', { useSuspense: false });
if (!ready) return <Loading />;  // must handle loading state yourself

Suspense の動作：デフォルトでは、翻訳の読み込み中に useTranslation によって React Suspense が発生します。アプリ（または該当するサブツリー）を <Suspense fallback="loading"> でラップしてください。

2. withTranslation HOC

import { withTranslation } from 'react-i18next';

function MyComponent({ t, i18n }) {
  return <p>{t('greeting')}</p>;
}
export default withTranslation()(MyComponent);           // default ns
export default withTranslation('common')(MyComponent);    // specific ns
export default withTranslation(['ns1', 'ns2'])(MyComponent); // multiple

Suspense を使用しない場合は、useSuspense={false} をプロパティとして渡し、props.tReady を確認します。

3. Translation レンダープロパティ

import { Translation } from 'react-i18next';

function MyComponent() {
  return (
    <Translation ns="common">
      {(t, { i18n }) => <p>{t('hello')}</p>}
    </Translation>
  );
}

4. Trans コンポーネント

翻訳文字列内に React 要素（リンク、太字テキスト、コンポーネント）を埋め込む必要がある場合にのみ、Trans を使用します。通常のテキストには、代わりに t() を使用してください。

import { Trans, useTranslation } from 'react-i18next';

function Welcome({ name, count }) {
  const { t } = useTranslation();
  return (
    <Trans i18nKey="userMessages" count={count}>
      Hello <strong title={t('nameTitle')}>{{name}}</strong>,
      you have {{count}} unread message.
      <Link to="/msgs">Go to messages</Link>.
    </Trans>
  );
}

翻訳 JSON：

{
  "userMessages_one": "Hello <1>{{name}}</1>, you have {{count}} unread message. <5>Go to messages</5>.",
  "userMessages_other": "Hello <1>{{name}}</1>, you have {{count}} unread messages. <5>Go to messages</5>."
}

名前付きコンポーネント（v11.6.0 以降） — インデックス付きタグよりもすっきり記述できます。

<Trans
  i18nKey="myKey"
  defaults="hello <italic>beautiful</italic> <bold>{{what}}</bold>"
  values={{ what: 'world' }}
  components={{ italic: <i />, bold: <strong /> }}
/>

JSON："myKey": "hello <italic>beautiful</italic> <bold>{{what}}</bold>"

シンプルな HTML 要素（v10.4.0 以降）： デフォルトでは、<br/>、<strong>、<i>、<p> は翻訳文字列内でそのまま保持されます（transSupportBasicHtmlNodes および transKeepBasicHtmlNodesFor オプションで制御します）。

インデックス番号のルール：Trans の子要素は、子要素配列内の位置に基づいて番号が付けられます。文字列と補間オブジェクトにもインデックスが割り当てられますが、タグで囲まれません。要素は <N>...</N> タグで囲まれます。

Trans コンポーネントのプロパティと高度なパターンについての詳細は、references/trans-component.md を参照してください。

一般的なパターン

言語の切り替え

function LanguageSwitcher() {
  const { i18n } = useTranslation();
  return (
    <select value={i18n.language} onChange={e => i18n.changeLanguage(e.target.value)}>
      <option value="en">English</option>
      <option value="tr">Türkçe</option>
    </select>
  );
}

コンポーネント外で t() を使用する

設定済みの i18n インスタンスを直接インポートします。

import i18n from './i18n';
i18n.t('my.key');

I18nextProvider（複数のインスタンス）

複数の i18next インスタンス（コンポーネントライブラリなど）をサポートする場合、または SSR の場合にのみ必要です。

import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';

<I18nextProvider i18n={i18n} defaultNS="translation">
  <App />
</I18nextProvider>

名前空間（複数の翻訳ファイル）

名前空間を使うと、翻訳を個別のファイルに分割し、遅延読み込みできます。

const { t } = useTranslation(['page1', 'common']);
t('key');                      // from 'page1' (first namespace)
t('key', { ns: 'common' });   // from 'common'

useTranslation、withTranslation、または Translation を使用するコンポーネントは、要求された名前空間が読み込まれるまで自動的に Suspense 状態になります。すべての翻訳を事前に読み込む必要はありません。

補間

{ "greeting": "Hello {{name}}, you are {{age}} years old" }

t('greeting', { name: 'Ali', age: 28 })

複数形

i18next では、ICU に似た複数形サフィックスを使用します。英語の場合：

{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

t('item', { count: 5 })  // → "5 items"

コンテキスト

{
  "friend_male": "A boyfriend",
  "friend_female": "A girlfriend"
}

t('friend', { context: 'male' })

ネスト

{
  "app": { "name": "MyApp" },
  "intro": "Welcome to $t(app.name)"
}

TypeScript のサポート

react-i18next >= 13.0.0 および i18next >= 23.0.1 が必要です。

型安全な翻訳を設定するには、https://www.i18next.com/overview/typescript の公式ガイドに従ってください。主な手順は次のとおりです。

1. リソースの型定義ファイルを作成します
2. リソースの型を使って i18next モジュールを拡張します
3. これにより、t 関数でアクセサー構文を使用できます：t($ => $.my.key)

SSR（Next.js、Remix、Gatsby）

• Next.js（App Router）：App Router パターンで i18next を直接使用します。references/ssr.md を参照してください
• Next.js（Pages Router）：react-i18next をラップする next-i18next を使用します
• Remix：remix-i18next を使用します
• Gatsby：gatsby-plugin-react-i18next を使用します

カスタム SSR では、useSSR フックまたは withSSR HOC を使用して、初期翻訳と言語をサーバーからクライアントに渡します：

import { useSSR } from 'react-i18next';
function InitSSR({ initialI18nStore, initialLanguage }) {
  useSSR(initialI18nStore, initialLanguage);
  return <App />;
}

詳しくは、references/ssr.md をお読みください。

テスト

最もシンプルな方法から最も徹底した方法まで、3 つのアプローチがあります：

1. フックをモックする（Jest）：

jest.mock('react-i18next', () => ({
  useTranslation: () => ({
    t: (key) => key,
    i18n: { changeLanguage: () => new Promise(() => {}) },
  }),
  initReactI18next: { type: '3rdParty', init: () => {} },
}));

2. コンポーネントをそのままエクスポートし、t を prop として渡す：

export { MyComponent };                              // for testing
export default withTranslation('ns')(MyComponent);   // for app
// In test: <MyComponent t={key => key} />

3. テストで i18next を完全にセットアップする（モックなし）：

import i18n from 'i18next';
import { initReactI18next, I18nextProvider } from 'react-i18next';
i18n.use(initReactI18next).init({
  lng: 'en', fallbackLng: 'en',
  resources: { en: { translationsNS: {} } },
});
// Wrap component: <I18nextProvider i18n={i18n}><MyComponent /></I18nextProvider>

スパイの例を含む詳しいテストガイドは、references/testing.md をお読みください。

React オプションリファレンス

i18next.init({ react: { ... } }) 内のオプション：

オプション	デフォルト	説明
bindI18n	'languageChanged'	再レンダリングをトリガーするイベント
bindI18nStore	''	再レンダリングをトリガーするストアイベント
transEmptyNodeValue	''	Trans で検索に失敗した場合の値
transSupportBasicHtmlNodes	true	翻訳文字列内の <br/> などを保持します
transKeepBasicHtmlNodesFor	['br','strong','i','p']	保持する HTML タグ
transWrapTextNodes	''	テキストノードをラップします（Google Translate の修正に 'span' など）
useSuspense	true	Suspense を有効／無効にします
keyPrefix	undefined	useTranslation の t 関数に自動で付与するプレフィックス

リファレンスファイル

各トピックの詳しいドキュメントについては、references/ ディレクトリ内の以下のファイルをお読みください：

• references/trans-component.md — Trans コンポーネントの完全な API、props、インデックス番号、名前付きコンポーネント、props の上書き、リスト、ICU 形式の使用方法
• references/testing.md — Jest のモック、スパイ、i18next の完全なセットアップを使った詳しいテストパターン
• references/ssr.md — Next.js、Remix、Gatsby、および useSSR/withSSR を使ったカスタム SSR のパターン