ローカルの翻訳とは？

ローカルの翻訳は、CDN（Content Delivery Network）から取得するのではなく、アプリのバンドル内に保存されます。ビルドプロセスに gtx-cli translate コマンドを追加すると、JSON 形式で翻訳が生成されます。最後のステップは、これらの翻訳をアプリで使用できるように取り込むことです。

これには次の2つの方法があります:

1. アプリのバンドル内（ローカル）：生成後、翻訳をアプリのバンドルに保存する
2. CDN 上（デフォルト）：実行時に CDN から翻訳を取得する

デフォルトでは、gt-next は General Translation の CDN から翻訳を取得します。弊社の API を使ってアプリを翻訳する場合、翻訳は自動的に当社の CDN に保存されます。

トレードオフ

ローカルの翻訳の利点

• 読み込みの高速化: ローカルの翻訳はアプリから直接提供され、CDN（コンテンツ配信ネットワーク）経由の翻訳よりも高速に読み込まれます
• 外部サービスに依存しない: アプリが翻訳を読み込めるかどうかは、CDNの稼働状況に左右されません。指定したlocaleの翻訳が見つからない場合、アプリは自動的にデフォルト言語へフォールバックします
• オフラインでも動作: 翻訳はアプリに同梱されています

ローカルの翻訳のデメリット

• バンドルサイズの増加: ローカルの翻訳はアプリのバンドルサイズを増やし、初回の読み込みが遅くなる可能性があります
• コンテンツ管理: 翻訳を編集するたびに、新しい翻訳を含めてアプリを再デプロイする必要があります

セットアップ

ステップ 1: ロード関数を作成

./src 配下に loadTranslations.[js|ts] というファイルを作成し、次の内容を追加します:

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig は、src/ ディレクトリまたはプロジェクトのルートから loadTranslations.[js|ts] ファイルを自動的に検出します。

ステップ 2：CLI の設定

設定コマンドを実行し、ローカルストレージを選択します。

npx gtx-cli configure

プロンプトが表示されたら:

• CDN に保存しますか? 「No」を選択
• Translation directory: ./public/_gt と入力

または、gt.config.json ファイルを手動で設定してローカルの翻訳を使用することもできます。詳しくは CLI Configuration ドキュメント を参照してください。

ステップ 3: 翻訳を生成する

これで translate コマンドを実行すると、翻訳が自動的にダウンロードされ、コードベースに取り込まれます。

npx gtx-cli translate

翻訳は public/_gt/ に保存され、アプリに同梱されます。

ビルドへの統合

Next.js のビルドプロセス

ビルドスクリプトに翻訳生成を追加します：

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

CI/CD パイプライン

# .github/workflows/deploy.yml
- name: 翻訳を生成
  run: npx gtx-cli translate
  
- name: アプリケーションをビルド  
  run: npm run build

よくある問題

翻訳ファイルの不足

ビルド前に翻訳を生成していることを確認してください:

# ❌ 翻訳なしでビルド
<...YOUR_BUILD_COMMAND...>

# ✅ 最初に翻訳を生成
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

インポートパスのエラー

load 関数内でディレクトリ構造を正しく合わせてください:

// ❌ 間違ったパス
const t = await import(`../translations/${locale}.json`);

// ✅ public/_gt の正しいパス
const t = await import(`../public/_gt/${locale}.json`);

バンドルサイズが大きい場合

多言語対応のアプリでは、コード分割を検討してください。

// 必要な時のみ翻訳を読み込む
export default async function loadTranslations(locale: string) {
  // ロケールがアクティブな場合のみ読み込む
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

次のステップ

• Middleware Guide - 言語検出とルーティング
• Languages Guide - 対応言語の設定
• APIリファレンス: