移行
プロジェクトを gt-next へ移行する方法
概要
このガイドでは、すでに他の i18n ライブラリを使用しているプロジェクトを gt-next へ移行するための手順を説明します。
また、移行をできるだけスムーズに進めるためのヒントやベストプラクティスも併せて紹介します。
前提条件
- 現在、他の i18n ライブラリを使用しているプロジェクトがあること
gt-nextライブラリの基本的な知識があること
なぜ移行するのか？
プロジェクトを gt-next へ移行したくなる理由は数多くあります。
その一部をご紹介します:
- JSON ファイルは不要: もう JSON ファイルで翻訳を管理する必要はありません。 すべてのコンテンツはコードと同じ場所、つまりインラインで管理できます。
- 自動翻訳: CLI ツールで文脈を理解した高品質な翻訳を自動生成します。 翻訳の完了を待つ必要はもうありません。
- 開発環境での検証: 開発中でも翻訳のホットリロードで手軽に試せます。
セットアップ
gt-next と gtx-cli（CLI ツール）をインストールします。
npm i gt-next gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cliプロジェクトのルートに gt.config.json を作成し、defaultLocale プロパティと locales 配列を定義します。
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}次に、アプリのルートレイアウトに <GTProvider> コンポーネントを追加します。
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}続いて、next.config.js に withGTConfig を追加します。
import withGTConfig from 'gt-next/config'
const nextConfig = {
// Your next.config.ts options
}
export default withGTConfig(nextConfig, {
// Your GT configuration
})詳細な手順は、クイックスタートガイドをご覧ください。
ここまでで、選択肢は3つあります。
- プロジェクト全体を
gt-nextに完全移行し、既存の i18n ライブラリを削除する。 - プロジェクトは完全移行しつつ、既存の i18n ライブラリの dictionaries を引き続き使用する。
- 当面は既存の i18n ライブラリを使い続け、プロジェクトの一部のみを
gt-nextに移行する。
各オプションの詳細は、移行戦略を参照してください。
移行戦略
オプション 1: プロジェクト全体を完全移行する
このオプションは最も分かりやすい一方で、一度に最も多くのコード変更が必要になります。
プロジェクトのセットアップが完了したら、既存の旧 i18n ライブラリの使用箇所をすべて検索し、gt-next に置き換えてください。
アプリで useTranslations などの React フックを使用している場合は、コードベース内の useTranslations のすべての使用箇所を検索し、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>
}
// または
export default function MyComponent() {
return <T>こんにちは、世界！</T>
}古い i18n ライブラリを使っている箇所すべてに対して同様に実行してください。
オプション 2: プロジェクトを完全移行しつつ、既存の i18n ライブラリの dictionaries を使い続ける
プロジェクトを gt-next に移行したいが、既存の i18n ライブラリの dictionaries は使い続け、
新規コンテンツに対してのみ GT のインライン機能を使いたいとします。
この場合は、オプション 1 と同様の手順を取れます。
既存の i18n ライブラリの使用箇所（例: useTranslations フック）をすべて見つけ、gt-next の useTranslations フックに置き換えます。
useTranslations フックは他の i18n ライブラリの useTranslations フックと非常に似た挙動で、同様に使用できます。
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}設定面では、プロジェクトのルートまたは src ディレクトリに dictionary.[js|ts|json] ファイルを作成する必要があります。
既存の dictionary ファイルの内容をこの新しいファイルにコピーしてください。
next.config.js の初期化関数 withGTConfig は、プロジェクトのルートまたは src ディレクトリにある dictionary ファイルを自動的に検出します。
詳細は dictionaries ガイドを参照してください。
オプション3: 当面は旧i18nライブラリを使い続け、プロジェクトの一部だけをgt-nextに移行する
このオプションは最も柔軟で、一度に必要なコード変更を最小限に抑えられます。
この場合、オプション2と同様の方針を取りつつ、プロジェクトの一部のみをgt-nextに移行します。
たとえば、いくつかのコンポーネントでは旧i18nライブラリを使い続け、その他や新規コンテンツにはgt-nextだけを使用できます。
このオプションは推奨されません。プロジェクト内で2種類のi18nライブラリを併用する必要があり、管理が複雑化して不具合の原因になる可能性があるためです。
移行のコツ
1. 可能な限り useGT フックまたは <T> コンポーネントを使う
可能なかぎり、useGT フックまたは <T> コンポーネントの利用をおすすめします。
そうすることで、今後のコンテンツ編集がぐっと楽になり、コードベースの可読性も大きく向上します。
2. 既存コンテンツには useTranslations フックを使う
useTranslations フックは、既存の dictionaries をそのまま活用するのに最適です。
移行を容易にするために提供していますが、新規コンテンツでの使用は推奨しません。
3. AIの利用
プロジェクト移行をAIで支援する場合は、以下から LLMs.txt と LLMs-full.txt を入手できます:
このガイドはどうでしたか？