共有文字列の翻訳

概要

共有文字列とは、アプリの複数箇所で使われる文字列や定数のことです。

たとえば、複数のコンポーネントで使われる文字列や、複数のファイルで使われる定数があるかもしれません。

従来の i18n ライブラリでは、共有文字列ごとに辞書を作成する必要があります。

このガイドでは、msg() 関数と useMessages() フックを使って、React アプリの共有文字列を手軽に国際化する方法を説明します。

本ガイドでは次の内容を扱います:

msg() 関数を使うべきタイミング

msg() 関数と useMessages() フックの使い方

変数の利用

例

よくある落とし穴

`msg()` 関数を使うべきとき

msg() 関数は、翻訳対象の文字列に印を付けるためのシンプルな関数です。

文字列を含む共通オブジェクトの例を見てみましょう:

src/navData.ts

export const navData = {
  home: {
    label: 'Home',
    description: 'The home page',
    icon: 'home',
    href: '/',
  },
  about: {
    label: 'About',
    description: 'Information about the company',
    icon: 'info',
    href: '/about',
  },
}

通常、このオブジェクトを国際対応にするには、各文字列に対応する辞書エントリを作成するか、翻訳済みのデータを返す関数にリファクタリングする必要があります。

たとえば、次のようにします:

src/navData.ts

export const getNavData = (t: (content: string) => string) => ({
  home: {
    label: t('Home'),
    description: t('The home page'),
    icon: 'home',
    href: '/',
  },
  about: {
    label: t('About'),
    description: t('Information about the company'),
    icon: 'info',
    href: '/about',
  },
})

アプリ内で navData をインポートしていた箇所はすべて、代わりに getNavData(t) を呼び出す必要があります。

src/app/page.tsx

import { getNavData } from '@/navData';

export default function Home() {
  const t = useGT();
  const navData = getNavData(t);
  return <div>{navData.home.label}</div>;
}

これは多くの手間につながる可能性があります。そこで解決策として msg() 関数を使います。

`msg()` 関数の使い方

msg() 関数を使うには、文字列をそのまま関数に渡します。この関数は、翻訳に利用できる特殊なエンコード済み文字列を返します。

src/navData.ts

import { msg } from 'gt-react';

export const navData = [
  {
    label: msg('Home'), // 出力の型は `string`
    description: msg('The home page'),
    icon: 'home',
    href: '/',
  },
  {
    label: msg('About'),
    description: msg('Information about the company'),
    icon: 'info',
    href: '/about',
  },
]

次に、そのエンコード済み文字列を useMessages() フックに渡します。

src/app/page.tsx

import { useMessages } from 'gt-react';
import { navData } from '@/navData';

export default function Home() {
  const m = useMessages();
  return (
    <div>
      {navData.map((item) => (
        <div key={item.label}>{m(item.label)}</div>
      ))}
    </div>
  );
}

注意: msg() 関数が返す文字列はエンコードされており、元の入力文字列とは異なります。元の文字列を取得したい場合は、decodeMsg() でデコードしてください。

変数の使用

文字列がテンプレート文字列で変数を含む場合、msg() 関数にその変数を渡せます。

テンプレート文字列内の ${} 記法を {variable} に変更し、msg() の第2引数として変数名をキーとするオブジェクトを渡します。

src/navData.ts

const items = 100;
export const pricing = [
  {
    name: 'Basic',
    price: 100,
    description: `The basic plan includes ${items} items`
  },
]

次のように書き換えます:

src/navData.ts

import { msg } from 'gt-react';

const items = 100;
export const pricing = [
  {
    name: 'Basic',
    price: 100,
    description: msg('The basic plan includes {items} items', { items })
  },
]

{items} プレースホルダーは items 変数の値に置き換えられます。

これにより、翻訳内で動的な値を表示できます。

API の詳細は、API reference を参照してください。

gt-react は ICU メッセージ形式をサポートしており、変数のフォーマットも可能です。

const price = 100;
msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });

ICU メッセージ形式は、変数をフォーマットするための強力な方法です。詳細は、ICU message format documentation を参照してください。

例

共有のグローバルオブジェクトを翻訳する

src/llms.ts

import { msg } from 'gt-react';

export const llmData = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: msg('GPT-4.1 is a large language model developed by OpenAI'),
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: msg('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
  },
];

src/app/page.tsx

import { llmData } from '@/llms';
import { useMessages } from 'gt-react';

export default function MyComponent() {
  const m = useMessages();
  return (
    <div>
      {llmData.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{m(llm.description)}</p>
        </div>
      ))}
    </div>
  )
}

src/llms.ts

export const llms = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: 'GPT-4.1 is a large language model developed by OpenAI',
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
  },
]

src/app/page.tsx

import { llms } from '@/llms';

export default function MyComponent() {
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

関数の返り値を翻訳する

src/llms.ts

import { msg } from 'gt-react';

function mockData() {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      company: 'OpenAI',
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      company: 'Anthropic',
    },
  ];
}

export function getData() {
  const data = mockData();
  const modifiedData = data.map((item) => ({
    ...item,
    description: msg('{name} is a large language model developed by {company}', {
      name: item.name,
      company: item.company,
    }),
  }));
  return modifiedData;
}

src/app/page.tsx

import { getData } from '@/llms';
import { useMessages } from 'gt-react';

export default function MyComponent() {
  const m = useMessages();
  const data = getData();
  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>
          <h1>{item.name}</h1>
          <p>{m(item.description)}</p>
        </div>
      ))}
    </div>
  )
}

src/llms.ts

import { msg } from 'gt-react';

function mockData() {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      company: 'OpenAI',
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      company: 'Anthropic',
    },
  ];
}

export function getData() {
  const data = mockData();
  const modifiedData = data.map((item) => ({
    ...item,
    description: `${item.name}は${item.company}が開発した大規模言語モデル（LLM）です`,
  }));
  return modifiedData;
}

src/app/page.tsx

import { getData } from '@/llms';

export default function MyComponent() {
  const data = getData();
  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>
          <h1>{item.name}</h1>
          <p>{item.description}</p>
        </div>
      ))}
    </div>
  )
}

よくある落とし穴

`useMessages()` の呼び出し忘れ

msg() は入力文字列をエンコードするため、そのまま JSX などで直接使用することはできません。

エンコード済みの文字列をそのまま使おうとすると、次のような変な文字列になります:

const encodedString = msg('Hello, world!');
console.log(encodedString); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="

これを解決するには、useMessages() フックを使って翻訳済みの文字列を取得します。

import { useMessages } from 'gt-react';

const encodedString = msg('Hello, world!');

export default function MyComponent() {
  const m = useMessages();
  return <div>{m(encodedString)}</div>; // 現在の言語での "Hello, world!"
}

また、元の文字列を復元したい場合は、decodeMsg() 関数を使用します。

import { decodeMsg } from 'gt-react';

const encodedString = msg('Hello, world!');
const decodedString = decodeMsg(encodedString);
console.log(decodedString); // "Hello, world!"

動的コンテンツを `msg()` で包む

すべての文字列はビルド時に既知である必要があります。つまり、動的コンテンツを msg() で包むことはできません。

たとえば、次は無効です:

const dynamicContent = msg(`Hello, ${name}`);

これを解決するには、動的部分を変数として用意し、それを msg() に渡します。

const dynamicContent = msg('Hello, {name}', { name });

CLI ツールは、動的コンテンツを msg() で包もうとすると警告します。

次のステップ

msg() の API リファレンスをご覧ください。
useMessages() の API リファレンスをご覧ください。
<T> コンポーネントについてさらに詳しく学びましょう。

共有文字列の翻訳

このページについて