Context Crawler：better-i18n によるAI駆動のウェブサイト・リポジトリ解析でスマートな翻訳を実現

better-i18n がプロダクトからAIコンテキストを構築する方法

多くのローカライゼーションワークフローは手作業から始まります。誰かが文字列にタグを付け、ファイルをエクスポートし、見落としがないことを願います。better-i18n は異なるアプローチを採用しています。Context Crawler は、ウェブサイトのクロールとリポジトリのスキャンという2つの強力な解析モードを組み合わせて、AIによる翻訳の精度を飛躍的に高めるリッチなコンテキストを自動的に構築します。

結果として、AIトランスレーターがブランド、プロダクトの語彙、技術スタックを理解したうえで翻訳を開始するワークフローが実現します。

ウェブサイト解析：Firecrawl搭載のブランドディスカバリー

Context Crawlerのウェブサイト解析モードは、Firecrawl APIを使用して、指定したURLのコンテンツを体系的にクロール・抽出します。これは単純なHTMLスクレイピングではありません。FirecrawlはJavaScriptレンダリングされたページ、SPA、動的コンテンツを処理して、ユーザーが実際に目にするコンテンツをキャプチャします。

ウェブサイト解析の仕組み

1. URLを入力 — プロダクトのマーケティングサイト、ドキュメント、またはその他のWebプロパティを入力します。クローラーは公開アクセス可能なURLを受け付けます。
2. Firecrawlによる抽出 — Firecrawl APIがページをレンダリングし、内部リンクをたどって、見出し、本文テキスト、ナビゲーションラベル、CTA、メタデータを含む構造化コンテンツを抽出します。
3. 用語の検出 — AI解析がクロールしたすべてのページにわたって、繰り返し出現する用語、ブランド固有の言語、プロダクト名、機能名、ドメイン固有の語彙を識別します。
4. 候補の提案 — 検出された用語は、提案された定義、コンテキストノート、頻度データとともにグロッサリー候補として提案されます。各候補には、その用語が見つかったソースURLが含まれます。

ウェブサイト解析でキャプチャされるもの

• ブランド用語 — サイト全体で一貫して使用されるプロダクト名、機能名、料金プランのラベル、独自の用語
• ナビゲーションパターン — プロダクトの語彙を定義するメニューラベル、パンくずテキスト、CTAの言語
• ドメイン語彙 — プロダクトが使用する業界固有の用語で、正確かつ一貫した翻訳が必要なもの
• トーンとボイスのシグナル — コンテンツがフォーマル、カジュアル、テクニカル、マーケティング志向のいずれかを示すコンテキスト。AIが適切なレジスターで翻訳するのに役立ちます。

ウェブサイト解析のユースケース

• 新規プロジェクトのセットアップ — ローカライゼーション開始前にマーケティングサイトをクロールして、数週間ではなく数分でグロッサリーとコンテキストプロファイルをブートストラップします。
• 競合分析 — ターゲット市場の競合サイトをクロールして、競合が類似コンセプトをどのように翻訳しているかを理解し、自社のグロッサリー決定に役立てます。
• コンテンツ監査 — 定期的に再クロールして、前回のグロッサリー更新以降に生まれた新しい用語を検出します。

リポジトリ解析：フレームワークと用語の検出

Context Crawlerのリポジトリ解析モードは、GitHubリポジトリに接続し、コードベースの深い解析を実行して翻訳に関連するコンテキストを抽出します。

リポジトリ解析の仕組み

1. GitHubリポジトリを接続 — リポジトリURLを入力します。クローラーはパブリックリポジトリに直接アクセスし、プライベートリポジトリにはGitHub連携を通じてアクセスします。
2. フレームワーク検出 — アナライザーが技術スタックを識別します（React、Next.js、Vue、Angular、Svelte、Flutter、React Nativeなど）。これにより、どのi18nパターンを探すか、コードをどのように解析するかが決まります。
3. i18nパターン認識 — 検出されたフレームワークに基づいて、アナライザーは既存の翻訳関数の呼び出し（t()、useTranslations()、$t()、tr()など）を見つけ、プロジェクトがどのように翻訳を構造化しているかをマッピングします。
4. 用語の抽出 — アナライザーはハードコードされた文字列、コンポーネント名、ルートラベル、その他のプロダクト語彙を表すユーザー向けテキストを識別します。
5. コンテキストプロファイルの生成 — すべての調査結果が、検出されたフレームワーク、i18nライブラリの使用状況、名前空間の構造、用語候補を含むコンテキストプロファイルにまとめられます。

リポジトリ解析で検出されるもの

• フレームワークとi18nライブラリ — スタックを自動検出し、AIによる翻訳が正しいフォーマット規約（ICU MessageFormat、i18next補間、Flutter ARBなど）を使用するようにします。
• 名前空間の構造 — プロジェクトがどのように翻訳キーを整理しているかを把握し、新しい翻訳が同じパターンに従うようにします。
• 既存の用語 — コードベース全体ですでに使用されている用語を特定し、グロッサリーに追加すべきものを識別します。
• 文字列パターン — 翻訳ルールを通知するユーザー向け文字列の一般的なパターン（日付形式、数値形式、複数形の処理方法）。

ASTベースのキー検出

コンテキスト構築を超えて、CLIのscanコマンドはソースコードをシンタックスツリーレベルで解析します。脆弱な正規表現マッチングではありません。React JSX、useTranslations、getTranslationsパターンをネイティブに理解します。これにより、<h1>Welcome back</h1>のようなユーザー向け文字列とclassName="flex items-center"のような技術的な文字列を誤検知なしに区別できます。

検出対象：

• ハードコードされたJSXテキスト — t()呼び出しでラップすべき<h1>Hello</h1>のようなコンテンツ
• ハードコードされたJSX属性 — <img alt="Company logo" />のようなユーザーが目にする属性
• トーストと通知の文字列 — toast.error("Something went wrong")のような呼び出し
• ロケールベースの三項ロジック — 手動ロケール処理を示すlocale === 'en' ? 'Hi' : 'Hola'のようなパターン
• 文字列変数 — ユーザー向けと思われるテキストを含む変数

インテリジェントに無視するもの：

• TailwindとCSSのクラス名
• URL、ファイルパス、画像ソース
• HTMLエンティティ（&、"）
• SCREAMING_CASEの技術定数
• 数値と非テキスト値

better-i18n scan              # カレントディレクトリをスキャン
better-i18n scan --dir ./src  # 特定のディレクトリをスキャン
better-i18n scan --staged     # ステージ済みファイルのみ（pre-commitフック用）
better-i18n scan --ci         # 問題が見つかった場合はexit code 1
better-i18n scan --format json # ツール連携用JSON出力
better-i18n scan --verbose    # スキャン監査付きの詳細出力

名前空間の解決

スキャナーはレキシカルスコープトラッキングを使用して、クライアントコンポーネントとサーバーコンポーネントの両方で名前空間を自動的に解決します。これにより、検出されたキーにはキー名だけでなく完全な名前空間パスが含まれます。

フックを使用するクライアントコンポーネントの場合：

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // 検出結果: hero.title

非同期関数を使用するサーバーコンポーネントの場合：

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // 検出結果: welcome.title

スキャナーはオブジェクト形式（getTranslations({ locale, namespace: 'settings' })）と、名前空間が提供されないルートスコープのトランスレーターも処理します。変数やテンプレートリテラルを使用した動的名前空間は--verboseモードで報告され、誤検知を避けるためメトリクスから除外されます。

解析からグロッサリーへ：完全なパイプライン

Context Crawlerのウェブサイト解析とリポジトリ解析モードは、グロッサリー管理システムに直接フィードします：

1. クロール — Firecrawlによるウェブサイト解析でブランド用語を抽出し、リポジトリ解析でフレームワークのコンテキストと既存の用語を検出します。
2. 提案 — 検出された用語はドラフト状態のグロッサリー候補として提案されます。
3. レビュー — チームが提案された用語をレビューし、定義と翻訳を必要に応じて編集します。
4. 承認 — 承認された用語はAI翻訳とレビューエディターで即座に適用されます。
5. 同期 — 承認された用語はプロバイダーレベルの適用のためにDeepLに同期できます。

このパイプラインにより、「グロッサリーがない」状態から「AIによる翻訳で200のブランド用語を適用」する状態に、一日午後の作業で移行できます。

Sync：ローカルとクラウドの比較

syncコマンドは、コードが使用しているものとbetter-i18nに存在するものの間のギャップを橋渡しします。scanと同じ方法でコードベースをスキャンし、better-i18n APIを照会してキーセットを比較します。

出力は明確な比較レポートです：

• リモートに不足 — コードで参照されているがbetter-i18nにまだアップロードされていないキー。これらはユーザーが未翻訳のまま見てしまう可能性のある文字列です。
• コードで未使用 — better-i18nには存在するがソースのどこにも参照されていないキー。これらはクリーンアップの候補です。

better-i18n sync              # グループ化されたツリー出力
better-i18n sync --summary    # 高レベルのカバレッジメトリクスのみ
better-i18n sync --format json # CI自動化用のJSON出力
better-i18n sync -d ./src     # 特定のディレクトリをスキャン

ツリー出力はキーを名前空間でグループ化し、アプリのどの部分にギャップがあるかを簡単に確認できます。--verboseフラグは、不変条件チェック、スコーピングサマリー、特定のキープローブを含む詳細な監査ログを提供します。

カバレッジメトリクス

syncコマンドはパーセンテージベースのカバレッジメトリクスを提供します：

• ローカルからリモートへのカバレッジ：コードで使用されているキーのうち、better-i18nに存在する割合
• リモートの使用状況：better-i18nのキーのうち、コードで実際に使用されている割合

これらの数値により、チームはいつでも翻訳の健全性を明確に把握できます。ターミナル出力で確認するか、JSON出力から抽出してカスタムダッシュボードやレポートに利用できます。

CI連携

scanとsyncはどちらも自動化パイプラインでの実行を想定して設計されています。scanで--ciを使用するとハードコードされた文字列が検出された際にビルドを失敗させ、sync出力をjqでパイプして不足するキー数に基づいてデプロイを制御できます。

# GitHub Actionsの例
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

pre-commitフックには、ステージ済みファイルのみをスキャンしてフィードバックを素早くします：

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

対象外の機能

明確な期待値を設定するために：

• ビジュアルコンテキストのキャプチャなし — CLIはコードレベルで動作し、レンダリングされたUIでは動作しません。文字列がどこに表示されるかのスクリーンショットやビジュアルプレビューはありません。
• リアルタイム監視なし — scanとsyncはオンデマンドまたはCIパイプラインで実行されます。バックグラウンドウォッチャーやファイルシステムオブザーバーではありません。
• 古い翻訳の検出なし — syncコマンドは不足しているキーと未使用のキーを表示しますが、ソーステキストの変更に対して既存の翻訳が古くなっているかどうかは検出しません。

はじめに

1分以内にCLIをインストールして最初のスキャンを実行します：

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

次に、better-i18nプロジェクトに接続してクラウドと比較します：

better-i18n sync

ウェブサイト解析を開始するには、プロジェクトダッシュボードのAIコンテキストセクションにアクセスし、URLを入力して、FirecrawlにブランドのTerminologyを抽出させます。リポジトリ解析の場合は、GitHubリポジトリを接続して、アナライザーにフレームワークと既存の用語を検出させます。

設定オプション、検出ルール、高度な使用方法については、完全なCLIドキュメントをご覧ください。

翻訳コンテキストと用語発見の自動化に準備ができましたか？アカウントを作成するして最初のプロジェクトを接続してください。または、クローラーが発見した用語を適用するグロッサリー管理システムについて学ぶこともできます。