概要

このガイドでは、既に i18n ライブラリを使用しているプロジェクトを gt-react へ移行するために必要な手順を解説します。

また、移行をできるだけスムーズに進めるためのヒントやベストプラクティスも紹介します。

前提条件

• 現在、別の i18n ライブラリを使用しているプロジェクト
• gt-react ライブラリに関する基本的な理解

なぜ移行するのか？

プロジェクトを gt-react へ移行したくなる理由はいくつもあります。

その一部をご紹介します:

• JSON ファイル管理はもう不要: もう翻訳を JSON ファイルで管理する必要はありません。 コンテンツは本来あるべき場所であるコード内（インライン）に置けます。
• 自動翻訳: 当社の CLI ツールで、文脈に即した高品質な翻訳を自動生成します。 翻訳を待つ必要はもうありません。
• 開発での素早い検証: 翻訳のホットリロードにより、開発中でも簡単に翻訳を試せます。

セットアップ

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

{
  "defaultLocale": "en",
  "locales": ["en", "fr", "es"]
}

import { GTProvider } from 'gt-react'
import config from './gt.config.json'

<GTProvider {...config}>
  <App />
</GTProvider>

移行戦略

オプション 1: プロジェクト全体を一括移行する

このオプションは最もシンプルですが、その分、一度に最も多くのコード変更が発生します。

プロジェクトのセットアップが完了したら、既存の旧 i18n ライブラリの使用箇所をすべて検索し、gt-react に置き換えます。

アプリで useTranslation などの React フックを使用している場合は、コードベース内の useTranslation をすべて検索して useGT に置き換えます。

続いて、すべての文字列キーを実際の文字列に置き換える必要があります。

たとえば、旧コードが次のようになっている場合:

{
  "hello": {
    "description": "こんにちは、世界！"
  }
}

export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

次のものに置き換えてください：

export default function MyComponent() {
  const { t } = useGT()
  return <div>{t('こんにちは、世界！')}</div>
}
// OR
export default function MyComponent() {
  return <T>こんにちは、世界！</T>
}

旧 i18n ライブラリのすべての箇所で、同様の対応を行ってください。

オプション2: プロジェクトを完全移行しつつ、旧i18nライブラリのdictionariesを使い続ける

プロジェクトを gt-react に移行したいが、旧i18nライブラリのdictionariesは引き続き使い、新規コンテンツにのみGTのインライン機能を使いたいとします。

この場合、オプション1と同様の対応が可能です。

旧i18nライブラリの useTranslation フックなどの使用箇所をすべて見つけ、useTranslations フックに置き換えます。

useTranslations フックは useTranslation フックと非常に似た挙動で、同様に使用できます。

import { useTranslation } from 'react-i18next'
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

import { useTranslations } from 'gt-react'
export default function MyComponent() {
  const t = useTranslations()
  return <div>{t('hello.description')}</div>
}

設定面では、プロジェクトのルートまたは src ディレクトリに dictionary.[js|ts|json] ファイルを作成する必要があります。旧dictionaryファイルの内容をこの新しいファイルにコピーし、そのファイルを GTProvider コンポーネントに渡してください。

import { GTProvider } from 'gt-react'
import dictionary from './dictionary.json'
import config from './gt.config.json'

<GTProvider {...config} dictionary={dictionary}>
  <App />
</GTProvider>

詳細は dictionaries ガイドをご覧ください。

オプション3：当面は従来の i18n ライブラリを使い続け、プロジェクトの一部だけを gt-react に移行する

このオプションは最も柔軟で、一度に必要なコード変更も最小限で済みます。

この場合はオプション2と同様ですが、プロジェクトの一部だけを gt-react に移行します。

たとえば、一部のコンポーネントでは従来の i18n ライブラリを使い続け、その他のコンポーネントや新規コンテンツには gt-react のみを使用できます。

移行のヒント

1. 可能な限り useGT フックまたは <T> コンポーネントを使う

可能な限り、useGT フックまたは <T> コンポーネントの利用を推奨します。

これにより、今後のコンテンツ編集が大幅に楽になり、コードベースの可読性も大きく向上します。

2. 既存コンテンツには useTranslations フックを使用する

useTranslations フックは、既存の dictionaries をそのまま活用するのに最適です。

移行を円滑にするための手段として提供していますが、新規コンテンツでの使用は推奨しません。

3. AIの利用

プロジェクト移行にAIを用いる場合は、以下から LLMs.txt と LLMs-full.txt を入手できます:

• LLMs.txt
• LLMs-full.txt

これらのファイルには本ドキュメントの内容がすべて含まれているため、AIツールはプロジェクトの移行を支援するのに必要な情報へ一通りアクセスできます。