はじめに

General Translation React SDK は、React アプリケーション向けのオープンソースの国際化（i18n）ライブラリです。

この SDK は、他の一般的な i18n ライブラリと同等の機能を備え、React アプリケーションを簡潔かつ保守しやすい形で国際化できる包括的なツールセットを提供します。

SDK は General Translation プラットフォームなしでも単体で使用でき、他の i18n ライブラリと同様に動作します。

また、当社のプラットフォームと統合することで、次の強化機能も利用できます。

• 開発時の翻訳ホットリロード
• AI による自動翻訳
• General Translation プラットフォームとの翻訳同期
• 当社の翻訳 CDN とのネイティブ統合

コンセプト

このSDKで理解しておくべき主要なコンセプトは5つあります。

<GTProvider> コンポーネント

<GTProvider> コンポーネントは、現在の言語や該当する翻訳を含む翻訳コンテキストをアプリケーションに提供します。

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* アプリケーションのコンテンツ */}
      </div>
    </GTProvider>
  );
}

重要: プロバイダーはアプリケーション全体をラップし、可能な限りコンポーネントツリーの上位、たとえばルートの App コンポーネントに配置してください。

詳細は GTProvider の APIリファレンスを参照してください。

<T> コンポーネント

<T> コンポーネントは、アプリケーション内のコンテンツを翻訳するための推奨手段です。

任意の JSX 要素をラップできる React コンポーネントで、要素の内容をサポート対象の言語に自動的にレンダリングします。

例

<T>
  <div>こんにちは、世界！</div>
</T>

<T>
  <div>
    <h1> こちらに画像があります </h1>
    <img src="https://example.com/image.png" alt="例" />
  </div>
</T>

<T>
  `<T>`コンポーネントを使用すると、フォーマットを簡単に行うことができます。
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

<T> コンポーネントは、動的コンテンツのフォーマットのために、<Num>、<DateTime>、<Currency> などのvariable componentsと連携して動作します。

<T> コンポーネントガイドで、<T> コンポーネントのさまざまな使い方をご覧ください。

useGT フック

useGT フックは、いくつかのトレードオフはあるものの、<T> コンポーネントと同様に使える React フックです。

このフックは、文字列を翻訳するために使用できる関数を返します。

const t = useGT();

t('こんにちは、世界！');

<T> コンポーネントと比べると、useGT フックはコードベースでより柔軟に使えます。

たとえば、ネストした文字列を含む複雑なデータ構造がある場合は、<T> コンポーネントのほうが使いにくくなります。

const t = useGT();
const data = {
  title: t('こんにちは、世界！'),
  description: t('これは説明です'),
};

詳細は、strings ガイドの useGT フックの項目をご覧ください。

msg 関数

msg 関数は、複数のコンポーネント間で使われる、または設定オブジェクトに格納される文字列を翻訳対象としてマークするために使用します。

これは、ナビゲーションラベル、フォームメッセージ、アプリケーション内の複数箇所に表示されるテキストなどの共有コンテンツに特に有用です。

// 翻訳用の文字列をマーク
import { msg } from 'gt-react';

const navItems = [
  { label: msg('ホーム'), href: '/' },
  { label: msg('概要'), href: '/about' },
  { label: msg('お問い合わせ'), href: '/contact' }
];

// マークされた文字列をデコードして使用
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

The msg 関数は翻訳用メタデータとともに文字列をエンコードし、useMessages がそれをデコードします。

msg 関数の詳細は、共有文字列 ガイドをご覧ください。

useTranslations フック

useTranslations は、指定したキーの翻訳を取得するための関数を返す React のフックです。

const dictionary = {
  hello: {
    world: 'こんにちは、世界！',
  },
};

const translate = useTranslations();
translate('hello.world');

この挙動は、react-i18next や next-intl などの他の翻訳ライブラリと似ています。

useTranslations フックについて詳しくは、dictionaries ガイドをご覧ください。

詳細は useTranslations APIリファレンス を参照してください。

次のステップ

• SDK を使って React プロジェクトをセットアップする方法: クイックスタート
• <T> コンポーネントで JSX コンテンツを翻訳する方法: JSX 翻訳ガイド
• useGT フックで文字列を翻訳する方法: 文字列翻訳ガイド
• msg 関数で共有文字列を扱う方法: 共有文字列ガイド