Realtime Translator
対面の2人（日本語話者・英語話者）が1台のスマートフォンを共有し、リアルタイムに文字翻訳字幕を表示するWebアプリです。画面は上下に分割され、上側は相手が読みやすいよう180度回転して表示されます。
詳細な要件・仕様は docs/01_REQUIREMENTS.md / docs/02_SPECIFICATION.md / docs/03_STRUCTURE.md、デザインシステムは design.md を参照してください。
技術構成
- Next.js (App Router) / TypeScript / pnpm
- HeroUI v3 / Tailwind CSS v4
- Turso (libSQL) / Drizzle ORM
- OpenAI Realtime Translation API（WebRTC、
gpt-realtime-translate / gpt-realtime-whisper）
- Zod / Vitest / React Testing Library / Playwright
- Vercel（デプロイ）
ローカル起動
pnpm install
cp .env.example .env.local # 値を設定（下記「環境変数」参照）
pnpm dev
http://localhost:3000 を開きます。
環境変数
.env.local（Git管理外）に設定します。値は .env.example を参照してください。
| 変数 | 必須 | 説明 |
|---|
OPENAI_API_KEY | 任意 | 未設定時はモックモードで動作します |
TURSO_DATABASE_URL | 必須 | Turso DBのURL |
TURSO_AUTH_TOKEN | 必須 | Tursoの認証トークン |
APP_ENV | 任意 | development / test / production |
NEXT_PUBLIC_APP_NAME | 任意 | 表示名 |
NEXT_PUBLIC_ENABLE_MOCK_TRANSLATION | 任意 | trueでモック固定（既定値） |
DEVICE_ID_HASH_SALT | 任意 | 匿名端末IDのハッシュ化に使うsalt |
OPENAI_API_KEY は絶対にクライアントへ返しません（Route Handler内でのみ使用し、ブラウザには短命のクライアントシークレットのみを渡します）。
Turso / Drizzle
pnpm db:generate # スキーマからマイグレーションSQLを生成
pnpm db:migrate # Tursoへ適用
pnpm db:studio # Drizzle Studioを起動
スキーマは lib/db/schema.ts、マイグレーションSQLは drizzle/migrations/ にあります。
モックモード
NEXT_PUBLIC_ENABLE_MOCK_TRANSLATION=true（既定値）、または OPENAI_API_KEY 未設定時、/api/realtime/token が mock: true を返し、実際のOpenAI API呼び出しを行わずにサンプル字幕をストリーミング表示します。マイク許可・無音検知・DB保存・履歴表示は本番と同じコードパスを通ります。
実際のOpenAI Realtime APIに接続するには、.env.local の OPENAI_API_KEY を設定した上で NEXT_PUBLIC_ENABLE_MOCK_TRANSLATION=false にしてください（実APIの呼び出しが発生するため、通常の開発ではモックのままにすることを推奨します）。
テスト
pnpm lint # ESLint
pnpm typecheck # tsc --noEmit
pnpm test # Vitest（unit + integration）
pnpm test:e2e # Playwright（モックモードで実行）
pnpm check # lint + typecheck + test + build
デプロイ（Vercel）
main ブランチへのマージでProductionに、feature ブランチのpushでPreviewに自動デプロイされます。Vercelダッシュボードで環境変数（上記表）を Production / Preview / Development すべてに登録してください。
既知の制約
- 自動言語判定は補助機能です。誤判定の可能性があるため、常に手動の言語切り替えボタンが利用できます。
- 生の音声データは一切保存しません（DB・Vercelいずれにも保存対象外）。保存されるのは確定済みの原文・翻訳テキストのみです。
- レート制限はプロセス内メモリによる簡易実装です。Vercelのサーバーレス環境ではインスタンスごとに独立するため、厳密な制限ではなく最低限の誤操作防止として機能します。
- OpenAI APIキー未設定時は全機能をモックモードで確認できますが、実際の翻訳精度・レイテンシは実キー設定後の実機確認が必要です。
