ローカルの翻訳とは？

ローカルの翻訳は、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 に保存しますか？ 「いいえ」を選択
• 翻訳ディレクトリ： ./public/_gt と入力

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

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

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

npx gtx-cli translate

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

ビルドの統合

Next.js のビルドプロセス

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

{
  "scripts": {
    "build": "npx gtx-cli translate && <...あなたのビルドコマンド...>"
  }
}

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) {
  // locale が現在有効な場合にのみ読み込む
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

次のステップ

• Middleware ガイド - 言語の検出とルーティング
• 言語ガイド - 対応言語の設定
• APIリファレンス：