移行
プロジェクトを gt-next に移行する方法
概要
このガイドでは、既に i18n ライブラリを利用しているプロジェクトを gt-next へ移行するための手順を説明します。
移行をできるだけスムーズに進めるためのヒントやベストプラクティスも併せて提供します。
前提条件
- 現在、別の i18n ライブラリを使用しているプロジェクト
gt-nextライブラリに関する基本的な理解
なぜ移行するのか？
プロジェクトを gt-next に移行したくなる理由はいくつもあります。
代表的なものは次のとおりです。
- JSON ファイルは不要: もう JSON ファイルで翻訳を管理する必要はありません。 すべてのコンテンツをコード内（インライン）で扱えます。
- 自動翻訳: 当社の CLI（コマンドラインインターフェイス）ツールで、文脈を踏まえた高品質な翻訳を自動生成できます。 翻訳の準備を待つ必要はもうありません。
- 開発環境で試せる: 翻訳のホットリロードにより、開発中でも簡単に試行できます。
セットアップ
gt-next と CLI ツール gtx-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
})さらに詳しい手順は、クイックスタートガイドをご覧ください。
ここで選べる options は3つあります:
- プロジェクト全体を
gt-nextに完全移行し、従来の i18n ライブラリを削除する。 - プロジェクトは完全移行しつつ、従来の i18n ライブラリの dictionaries を使い続ける。
- 当面は従来の i18n ライブラリを使い続け、プロジェクトの一部のみを
gt-nextに移行する。
各 options の詳細は、移行戦略セクションを参照してください。
移行戦略
オプション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ライブラリのdictionaryは継続利用する
プロジェクトをgt-nextへ移行したいが、旧i18nライブラリのdictionaryはそのまま使い続け、
新規コンテンツに対してのみ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 を入手できます:
このガイドはいかがですか?