概要

このガイドでは、既存の 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('Hello, world!')}</div>
}
// または
export default function MyComponent() {
  return <T>Hello, world!</T>
}

古い i18n ライブラリを使っている箇所すべてに対して、同様に実施してください。

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

プロジェクトを gt-react へ移行したいが、旧i18nライブラリのdictionaryは引き続き使用し、 新規コンテンツでのみ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と同様の進め方ができますが、移行対象をプロジェクトの一部に限定します。

たとえば、いくつかのコンポーネントでは従来の 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 ツールはプロジェクトの移行を支援するために必要なすべての情報にアクセスできます。