ロケールの切り替え

アルファ

Lingo.dev Compiler はアルファ版です。動作は不安定で、本番環境での利用は推奨されません。API はリリースごとに変更される可能性があります。

Lingo.dev Compiler は、実行時にアクティブなロケールを読み書きできる useLingoContext() フックを提供します。言語スイッチャーやロケール対応コンポーネント、あるいはユーザーの言語設定に応じて変化するあらゆる UI の実装に活用できます。

useLingoContext() フック#

このフックは、現在のロケールと、それを変更する関数を含むオブジェクトを返します。

tsx

import { useLingoContext } from "@lingo.dev/compiler/react";

const { locale, setLocale } = useLingoContext();

プロパティ	型	説明
`locale`	`string`	現在アクティブなロケールコード（例: `"en"`、`"es"`）。
`setLocale`	`(locale: string) => void`	新しいロケールを設定します。デフォルトでは、永続化が行われ、ページが再読み込みされます。

言語スイッチャーの例#

ドロップダウン形式の言語スイッチャーコンポーネントです。

tsx

"use client"; // Required for Next.js App Router

import { useLingoContext } from "@lingo.dev/compiler/react";

const localeLabels: Record<string, string> = {
  en: "English",
  es: "Espanol",
  de: "Deutsch",
  fr: "Francais",
  ja: "日本語",
};

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      {Object.entries(localeLabels).map(([code, label]) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

Next.js では、言語スイッチャーは React フックを使うため、Client Component（"use client"）である必要があります。

setLocale を呼び出すと何が起こるか#

ロケールが保存される

デフォルトでは、新しいロケールは locale という名前の cookie に、max-age を 1 年として保存されます。これにより、ページの再読み込み後やブラウザーの再起動後も設定が維持されます。

ページが再読み込みされる

新しいロケールですべてのコンポーネントを再レンダリングするために、ページが再読み込みされます。Server Components はサーバー上で新しいロケールの翻訳を取得し、Client Components は更新後の辞書を受け取ります。

以降のリクエストで新しいロケールが使われる

次回のページ読み込み時に、Compiler は保存されたロケールを読み取り、対応する翻訳を返します。

永続化オプション#

デフォルトの永続化の仕組みは cookie ベースで、localePersistence で設定します。

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",       // Cookie name
      maxAge: 31536000,     // 1 year in seconds
    },
  },
}

オプション	デフォルト	説明
`type`	`"cookie"`	永続化の方式。
`config.name`	`"locale"`	cookie 名。
`config.maxAge`	`31536000`	cookie の有効期間（秒）。

カスタム永続化#

URL ベースのロケールルーティング、localStorage、またはカスタムヘッダーベースの検出を行う場合は、カスタムロケールリゾルバーを作成します。クライアントリゾルバー内の persistLocale エクスポートが、setLocale の呼び出し時の挙動を制御します。

// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  window.location.reload();
}

URL ベース、cookie ベース、ヘッダーベースのパターンを含む完全な例については、Custom Locale Resolvers を参照してください。

切り替えずにロケールを読み取る#

スイッチャーを用意せず、表示や条件付きレンダリングのために現在のロケールだけが必要な場合は、同じフックを使えます。

tsx

"use client";

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LocaleBadge() {
  const { locale } = useLingoContext();
  return <span>{locale.toUpperCase()}</span>;
}

次のステップ#

Custom Locale Resolvers

URL ベース、localStorage、ヘッダーベースの永続化

Configuration Reference

localePersistence オプション

Next.js Integration

Server Component と Client Component の挙動

Vite + React

クライアントサイドでのロケール切り替え