GitHub連携：リポジトリと翻訳を同期する

better-i18nはGitHubリポジトリに直接接続します。PushイベントはHMAC-SHA256で検証されたWebhookによる自動同期をトリガーし、翻訳の更新はPull Requestとして配信され、Doctor CIワークフローはすべてのCommitで翻訳の品質を保護します。

仕組み

インバウンド：コードからクラウドへ

GitHubにコードをPushすると、better-i18nがWebhookイベントを受信し、翻訳ファイルを同期します：

GitHubへのPush — チームがコードの変更をCommitします
Webhookが発火 — GitHubがHMAC-SHA256署名で検証されたpushイベントを送信します
ファイル同期 — 設定されたパターンに一致する翻訳ファイルがクラウドプロジェクトに同期されます
ダッシュボードの更新 — 新しいキーが表示され、変更された翻訳が反映されます

アウトバウンド：クラウドからコードへ

翻訳者がダッシュボード（またはAPI/MCP経由）で翻訳を更新した場合、リポジトリに公開します：

翻訳の更新 — ダッシュボード、REST API、またはMCPツール経由
Publish — publishTranslationsを呼び出すか、ダッシュボードのPublishボタンを使用します
Pull Request作成 — better-i18nが専用のBranchに更新された翻訳ファイルを含むPRを作成します
チームがレビューしてMerge — 標準的なコードレビューワークフローが適用されます

WebhookイベントとセキュリティWebhook

better-i18nはすべての受信イベントにHMAC-SHA256署名検証を使用したGitHub App Webhookを使用します。認証されていないペイロードは処理されません。

サポートされているWebhookイベント

イベント	動作
push	リポジトリからクラウドへの翻訳ファイル同期をトリガー
installation.deleted	連携を自動アンインストールしてクリーンアップ
installation.suspend —	Syncを一時停止 — 停止中はWebhookが処理されません
installation.unsuspend	Syncを再開 — Webhookが再び処理されます

すべてのWebhookペイロードは処理前にGitHubのHMAC-SHA256署名に対して検証されます。無効な署名は即座に拒否されます。

PRベースの翻訳ワークフロー

翻訳の更新は既存のコードレビュープロセスに従います：

翻訳者またはAIエージェントがbetter-i18nダッシュボードで翻訳を更新します
準備ができたら、翻訳をリポジトリに公開します
better-i18nは変更された翻訳ファイルのみを含むPull Requestを作成します
チームがdiffをレビュー — どのキーが変更され、どの言語が更新されたかを正確に確認できます
満足したらMerge — 翻訳は他のコード変更と同じワークフローでコードベースに反映されます

このアプローチの意味：

直接Pushなし — すべての翻訳変更はPRレビューを経由します
完全な監査証跡 — すべての翻訳変更がgit履歴に記録されます
CI検証 — 既存のCIパイプラインも翻訳PRに対して実行されます
ロールバックサポート — 翻訳PRを他のCommitと同様に元に戻せます

マルチリポジトリサポート

複数のリポジトリを単一のbetter-i18nプロジェクトに接続するか、同じリポジトリを複数のプロジェクトに接続できます。一般的な構成：

モノリポ — 翻訳プロジェクトを共有する複数のアプリを持つ1つのリポジトリ
マイクロフロントエンド — 共有翻訳セットに貢献する複数のリポジトリ
プラットフォーム + モバイル — 同じ翻訳ソースから同期するWebおよびモバイルリポジトリ

リポジトリ管理

ダッシュボードまたはtRPC APIを使用して接続されたリポジトリを管理します：

操作	tRPCメソッド
リポジトリを接続	`github.addRepository`
手動同期をトリガー	`github.syncRepository`
リポジトリを切断	`github.removeRepository`
リポジトリファイルを閲覧	`github.getSourceFiles`
利用可能なBranchを一覧	`github.listBranches`
リポジトリツリーを表示	`github.getTree`

Doctor CIワークフロー

Doctorワークフローはbetter-i18nがリポジトリ向けに生成できるGitHub Actionsワークフローです。すべてのPushとPull Requestで翻訳の健全性チェックを実行します。

Doctorがチェックする項目

不足している翻訳 — ソース言語には存在するがターゲット言語に不足しているキー
未使用キー — 翻訳ファイルに定義されているがコードで参照されていないキー
フォーマットの一貫性 — すべての言語でのICUメッセージ構文検証
カバレッジレポート — 言語ごとの翻訳完了率

Doctorのセットアップ

tRPC APIを使用してワークフローファイルを生成します：

github.createDoctorWorkflow

これにより、すべてのPushとPull Requestで実行される.github/workflows/i18n-doctor.ymlファイルがリポジトリに作成されます。

Doctor出力例

i18n Doctor Report
==================

Coverage:
  en: 100% (source)
  tr: 94.2% (missing 23 keys)
  de: 87.1% (missing 51 keys)

Unused keys: 12
Format errors: 0

Result: WARNING — 2 languages below 95% threshold

DoctorはGitHubのチェックシステムと連携しています — 不足している翻訳やフォーマットエラーを導入するPRには警告ステータスが表示されます。

GitHubの権限

better-i18nは最小限のGitHub権限を要求します：

権限	用途
Repository Contents	翻訳ファイルのみ読み書き（設定されたパターン）
Pull Requests	翻訳更新のPRを作成
Webhooks	Sync用のPushイベントを受信

設定されたパターン（例：locales/**/*.json）に一致するファイルのみにアクセスします。better-i18nはソースコード、設定ファイル、翻訳ファイルパス以外のものを読むことは一切ありません。

ファイルフォーマット

better-i18nはlocaleとnamespaceで整理されたJSON翻訳ファイルを使用します：

your-repo/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   ├── tr/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   └── de/
│       └── ...

better-i18nが同期するファイルパターンはプロジェクト設定で構成します。

CLI：コードベースからキーを検出

@better-i18n/cliはローカル開発とクラウドプロジェクトを橋渡しします。

ハードコードされた文字列をスキャン

npx @better-i18n/cli scan

React/Next.jsコードベースで未翻訳のテキストを検出します：

components/sign-up.tsx (11)
  24:13  missing  "Create an account"  i18n/jsx-text
  32:22  missing  "Name"               i18n/jsx-text

✖ 87 problems (87 missing translations)

対応：

useTranslations('namespace') — クライアントコンポーネント
getTranslations('namespace') — サーバーコンポーネント（Next.js App Router）
JSXテキスト、属性、localeベースの三項演算子

ローカルとクラウドを比較

npx @better-i18n/cli sync

コードにあってクラウドにないもの、クラウドにあってコードで使われていないものを表示します：

Coverage:
  Local → Remote: 59%
  Remote Used: 63%

⊕ Missing in Remote (473 keys)
  pages (300)
    affordableEnglishLearning (meta.title, meta.description, ...+12)

⊖ Unused in Code (386 keys)
  features (25)
    practiceSpeaking (title, subtitle, icon)

CI/CD連携

GitHub Actionsワークフローに追加します：

name: i18n Check
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx @better-i18n/cli scan --ci
      - run: npx @better-i18n/cli sync --format json

未翻訳の文字列を導入するPRをブロックします。すべてのPushで翻訳カバレッジを監査します。

Pre-Commitフック

# Huskyを使用
npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

// lint-stagedを使用
{
  "lint-staged": {
    "*.{tsx,jsx}": ["better-i18n scan --ci"]
  }
}

Sync追跡

すべてのSync操作は完全なステータスとログを持つジョブとして追跡されます：

// MCP tool: getSyncs
{
  "project": "your-org/your-project",
  "status": "completed",
  "type": "source_sync"
}

Syncタイプ：

initial_import — リポジトリ接続時の初回同期
source_sync — GitHub PushイベントによってトリガーされるSync
cdn_upload — CDNデプロイ
batch_publish — GitHubへの翻訳の公開

設定

i18n.config.ts

CLIはi18n.config.tsからプロジェクト設定を読み取ります：

export const project = "your-org/your-project";
export const defaultLocale = "en";

export const i18nWorkspaceConfig = {
  project,
  defaultLocale,
  lint: {
    include: ["src/**/*.tsx", "app/**/*.tsx"],
    exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
  },
};

はじめに

GitHub Appをインストール — dash.better-i18n.comでGitHubアカウントを接続します
リポジトリを追加 — github.addRepository経由で同期するリポジトリを選択します
ファイルパターンを設定 — 翻訳ファイルの場所をbetter-i18nに伝えます
Doctor CIを有効化 — github.createDoctorWorkflowでi18n健全性チェックワークフローを生成します
CLIをインストール — npm install -D @better-i18n/cli
Syncを開始 — コードをPushして、GitHubとクラウド間で翻訳が流れるのを確認します

GitHub連携はすべてのプランでご利用いただけます。

GitHub連携：リポジトリと翻訳を同期する – better-i18n