# General Translation React SDKs (gt-react, gt-next, gt-react-native): ロケールの管理
URL: https://generaltranslation.com/ja/docs/react/guides/managing-locales.mdx
---
title: ロケールの管理
description: 対応ロケールを設定し、React の言語切り替え機能を構築し、アクティブなロケールを取得または変更する方法。
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/configuring
    - /docs/react/guides/storing-translations

---

`en-US` や `fr` などのロケールコードは、ユーザーが選択した言語を適切な翻訳とフォーマット規則に結び付けます。

アプリで対応するロケールを宣言し、ユーザーがその中から選択できるようにし、UI で言語固有の動作が必要な場合はアクティブなロケールを取得します。

## ロケールの状態を理解する [#locale-state]

* **デフォルトロケール:** ソースコンテンツの言語であり、対応するロケールがない場合に使用される最終的なフォールバックです。
* **対応ロケール:** デフォルトロケールとターゲットロケールを含む、ユーザーが選択できるすべてのロケールです。
* **アクティブなロケール:** URL、保存された設定、ブラウザ設定、またはデフォルトに基づいて選択される対応ロケールです。

## 対応ロケールを宣言する [#declare]

[`defaultLocale`](/docs/react/reference/config#default-locale)を設定し、対象の[`locales`](/docs/react/reference/config#locales)を `gt.config.json` に記載します。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "de"]
}
```

React、TanStack Start、React Native では、これらの値を初期化時の呼び出しに渡します。Next.js では、[`withGTConfig`](/docs/react/nextjs/config)が `gt.config.json` を自動的に読み込みます。各フレームワークのセットアップについては、[General Translation の設定](/docs/react/guides/configuring)を参照してください。

## 言語切り替え機能を追加する [#switcher]

インターフェースに最も適したシンプルな方法を選択してください。

* React、Next.js、TanStack Start で既成のドロップダウンを使用するには、[`<LocaleSelector>`](/docs/react/reference/components/locale-selector) を使用します。
* サポートされている任意のフレームワークでカスタムの言語切り替え機能を作成するには、[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) を使用します。
* ボタンなど、指定したロケールに切り替えるコントロールには、[`useSetLocale`](/docs/react/reference/hooks/use-set-locale) を使用します。

### すぐに使えるセレクターを使用する

client component で [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) をレンダーします。props を指定しない場合、設定済みのすべてのロケールが一覧表示され、ユーザーが項目を選ぶとアクティブなロケールが切り替わります。

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    ```tsx
    import { LocaleSelector } from 'gt-react';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx
    import { LocaleSelector } from 'gt-next';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```tsx
    import { LocaleSelector } from 'gt-tanstack-start';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="React Native">
    *注: React Native は [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) をエクスポートしていません。以下のように、[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) を使ってカスタムの切り替え機能を実装してください。*
  </Tab>
</Tabs>

### カスタム言語切り替え機能を作成する

[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) は、アクティブなロケール、利用可能なロケール、設定関数、ローカライズされた表示名を1つのhookで提供します。使用するコントロールはフレームワークに合わせて選択してください。

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    ```tsx
    import { useLocaleSelector } from 'gt-react';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx
    'use client';

    import { useLocaleSelector } from 'gt-next';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```tsx
    import { useLocaleSelector } from 'gt-tanstack-start';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="React Native">
    ```tsx
    import { Button, View } from 'react-native';
    import { useLocaleSelector } from 'gt-react-native';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <View>
          {locales.map((localeCode) => (
            <Button
              key={localeCode}
              title={getLocaleProperties(localeCode).nativeNameWithRegionCode}
              disabled={localeCode === locale}
              onPress={() => setLocale(localeCode)}
            />
          ))}
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

Reactウェブアプリで直接ロケールを切り替えるだけでよい場合は、[`useSetLocale`](/docs/react/reference/hooks/use-set-locale) を呼び出してください。

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

function FrenchButton() {
  const setLocale = useSetLocale();
  return <button onClick={() => setLocale('fr')}>Français</button>;
}
```

## ロケールの選択を保存してルーティングする [#persistence]

[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)、[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)、または [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) でロケールを変更すると、その選択が保存され、新しい翻訳はフレームワークごとに異なる方法で適用されます。

* **React:** ロケールをcookieに保存し、デフォルトではページを再読み込みします。カスタムproviderの再読み込みcallbackを使用すると、ページ全体の再読み込みを置き換えられます。
* **Next.js App Router:** ロケールをcookieに保存し、サーバーコンポーネントツリーを更新します。ロケールミドルウェアが設定済みのpathルーティングを適用します。
* **Next.js Pages Router:** ロケールをcookieに保存します。providerの再読み込みcallbackを設定すると、Pages Routerでナビゲートして選択したロケールのページpropsを取得します。
* **TanStack Start:** ロケールをcookieに保存し、ページを再読み込みします。[`localeRouting`](/docs/react/reference/config#locale-routing) を有効にすると、対応するロケールのpathnameにナビゲートします。
* **React Native:** ロケールをネイティブストレージ (React Native Webでは `localStorage`) に保存し、providerのstateを更新してロケールの翻訳を読み込み、ブラウザでのナビゲーションなしに再レンダリングします。

公開ページでは、ロケールベースのURLにより、各言語版を共有可能かつインデックス可能にできます。ルーティングはフレームワーク固有のガイドで設定してください。

* [Next.js App Router ミドルウェア](/docs/react/nextjs/app-router-middleware)
* [Next.js Pages Router ロケールルーティング](/docs/react/nextjs/pages-router-middleware)
* [TanStack Start ロケールルーティング](/docs/react/tanstack-start/setup#locale-routing)

## アクティブなロケールを読み取る [#read]

言語固有の UI をレンダリングする際は、ロケールフックを使用します。

* [`useLocale`](/docs/react/reference/hooks/use-locale) はアクティブなロケールコードを返します。
* [`useDefaultLocale`](/docs/react/reference/hooks/use-default-locale) はソースロケールを返します。
* [`useLocales`](/docs/react/reference/hooks/use-locales) はサポートされているすべてのロケールコードを返します。
* [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) は、ページレイアウト用の `'ltr'` または `'rtl'` を返します。
* [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties) は、ロケールの名前、ネイティブ名、リージョン、スクリプト、その他の表示用メタデータを返します。

*注: `gt-tanstack-start` は現在 [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) と [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties) をエクスポートしていません。代わりに、`generaltranslation` の [`getLocaleProperties`](/docs/platform/core/reference/utility-functions/locales/get-locale-properties) を使ってロケールのメタデータを取得してください。*

Next.js では、これらのフックは同期的な App Router サーバーコンポーネントで動作します。非同期コンポーネントでは、`gt-next/server` の [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) と [`getLocaleDirection`](/docs/react/nextjs/reference/functions/get-locale-direction) を呼び出します。

```tsx
import { getLocale, getLocaleDirection } from 'gt-next/server';

async function Layout() {
  const locale = await getLocale();
  const dir = await getLocaleDirection();
  return <html lang={locale} dir={dir} />;
}
```

ロケールのマッチングとフォールバックの動作については、[`useLocale`](/docs/react/reference/hooks/use-locale) リファレンスページを参照してください。
## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/configuring
- /docs/react/guides/storing-translations