# BGA Codex 한국어 번역 도우미

Board Game Arena의 영어→한국어 번역 페이지에서 빈 원문을 최대 50개씩 Codex로 번역하고, 검증한 뒤 순차 저장하는 Microsoft Edge 확장 프로그램과 Windows 네이티브 호스트입니다. 기존의 수동 복사·검증·채우기 흐름도 계속 지원합니다.

자동화는 BGA 로그인 정보, 쿠키, 인증 헤더와 저장 요청 본문을 네이티브 호스트로 전달하거나 기록하지 않습니다. 저장 브리지는 번역 관련 요청의 URL 경로와 상태 코드만 확인합니다. BGA가 실제 사용자 포커스 이동에서만 저장하므로 확장은 현재 탭에 한해 Edge 디버거 입력 권한으로 번역란과 전용 포커스 지점을 클릭하며, 작업 종료 시 즉시 연결을 해제합니다.

## 한 번에 실행

최초 설치를 마친 뒤에는 프로젝트 루트의 `start-bga-automation.cmd`를 더블클릭하면 다음 항목이 함께 실행됩니다.

- 전용 Edge 프로필
- 이 프로젝트 폴더의 압축 해제 확장 프로그램
- BGA Codex 트레이 런처
- 기본 모듈 2624의 영어→한국어 번역 페이지

시작할 때 전용 Edge 프로필에 남아 있던 기존 탭과 창은 정리되고 새 번역 탭 하나만 유지됩니다. 일반 Edge 프로필의 탭은 건드리지 않습니다. 번역용 Edge의 마지막 창을 닫으면 트레이 런처도 함께 종료됩니다.

트레이 아이콘을 더블클릭하면 번역 페이지를 다시 열 수 있습니다. 우클릭 메뉴에서는 실행 기록 폴더를 열거나 런처를 종료할 수 있습니다. 다른 모듈을 열 때는 PowerShell 7(`pwsh`)에서 모듈 ID를 지정합니다.

```powershell
.\start-bga-automation.cmd -ModuleId 2841
```

동일한 기능은 `npm run start:automation` 또는 `pwsh -NoLogo -NoProfile -File scripts\start-bga-automation.ps1`로도 실행할 수 있습니다. `scripts` 폴더의 PowerShell 스크립트는 PowerShell 7 이상을 요구합니다. 전용 프로필은 `%TEMP%\bga-codex-edge-profile`에 유지되므로 BGA 로그인 상태를 재사용합니다.

진행 상황을 누적형 한 줄 로그로 모니터링하려면 별도 PowerShell 창에서 `pwsh -NoLogo -NoProfile -File scripts\watch-bga-progress.ps1`을 실행합니다. 기본적으로 모듈이 바뀌어도 모든 모듈의 최신 작업을 계속 추적합니다. 특정 모듈만 보려면 `-ModuleId 2664`를 추가합니다. 이 스크립트는 실행 기록을 읽기만 하며 상태가 갱신될 때 시각, 모듈, 단계, 단계별 경과시간, 전체 경과시간과 작업 내용을 출력합니다. `Ctrl+C`는 모니터만 종료합니다.

## 자동화 호스트 준비

PowerShell 7(`pwsh`)에서 다음 명령을 순서대로 실행합니다.

```powershell
pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\prepare-dotnet.ps1
pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\install-host.ps1
```

첫 명령은 프로젝트의 `.tools/dotnet`에 .NET 8 SDK를 준비합니다. 설치 명령은 `win-x64` self-contained 단일 실행 파일을 게시하고 현재 사용자 범위의 Edge Native Messaging 호스트 `com.bgatls.codex_host`를 등록합니다. Codex CLI는 현재 사용자의 로그인과 기본 모델을 그대로 사용합니다.

제거할 때는 다음 명령을 사용합니다. 번역 기준과 `runs/` 실행 기록은 삭제하지 않습니다.

```powershell
pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\uninstall-host.ps1
```

## Edge에 설치

1. Edge 주소창에 `edge://extensions`를 입력합니다.
2. 왼쪽 메뉴에서 **개발자 모드**를 켭니다.
3. **압축 풀린 파일 로드**를 누르고 이 프로젝트 폴더를 선택합니다.
4. BGA에 직접 로그인한 뒤 다음 형식의 번역 페이지를 엽니다.

   `https://boardgamearena.com/translation?module_id=1542&source_locale=en_US&dest_locale=ko_KR`

5. 페이지 오른쪽의 **BGA → Codex 번역 도우미** 패널을 사용합니다.

확장 파일을 수정한 후에는 `edge://extensions`에서 확장의 새로 고침 버튼을 누르고 BGA 페이지도 새로 고칩니다.

통합 런처는 확장 버전이 바뀌면 전용 프로필의 서비스 워커 캐시만 재생성한 뒤 Edge를 시작합니다. 따라서 새 네이티브 호스트와 이전 확장 서비스 워커의 메시지 계약이 어긋나는 문제를 방지하며, 일반 Edge 프로필과 BGA 로그인 쿠키는 건드리지 않습니다.

## 사용 흐름

### 자동 흐름

1. 패널에서 **자동 번역 시작**을 누릅니다.
2. 기존 `bga-ko-guide-v1/v2` JSON이 있으면 즉시 사용합니다.
3. 기본 화면의 `결과: N`을 순회별 원시 행 기준값으로 기록합니다. 구조화 기준이 없는 모듈은 비활성 임시 탭에서 `status=all` 기준 URL을 유지해 최대 5회 전체 페이지를 순회합니다. 고유 ID 합집합이 연속 2회 안정되면 즉시 확정하고, BGA 정렬 문제로 안정되지 않으면 5회 동안 관찰한 누적 합집합으로 진행합니다. 페이지 간 동일 ID는 중복 노출로 기록하되 내용이 다르면 실패합니다.
4. 호스트가 전체 코퍼스를 `texts/<module_id>/source-corpus.json`에 저장하고, Codex 라이브 검색으로 공식 한국어 자료를 먼저 조사한 뒤 `bga-ko-guide-v2` 후보를 만듭니다.
5. 공식 자료를 찾지 못하거나 조사 기능을 사용할 수 없으면 공식 자료 URL 입력 창에서 대기합니다. 트레이 검토 창에서 출처·용어·문체를 검토하고 **승인 후 계속**을 눌러야 번역을 시작합니다.
6. 확장이 응답을 검증합니다. 오류나 경고가 있으면 Codex가 최대 3회 보정합니다.
7. 오류와 경고가 모두 없어야 사람다운 길이 비례·무작위 대기와 함께 debugger의 실제 `focus → Ctrl+A → text input → blur` 흐름으로 한 항목씩 저장합니다.
8. 저장 요청이 확인되지 않으면 항목별로 두 번 재시도하고, 계속 실패하면 나머지 배치를 중단합니다.
   원문과 번역문이 같은 항목(예: `<b>${card_name}</b>`)은 저장 전에 확인 팝업을 예상하고, 새로 나타나는 확인창을 한 번 자동 승인한 뒤 저장 응답을 확인합니다. 새 Svelte UI는 동일 번역 안내 문구와 확인 버튼을 함께 식별하며, 승인 후 저장 응답을 받으면 실행 기록에 `identical-translation-confirmed`를 남깁니다.
9. 한 배치를 저장하면 현재 번역 탭을 새로고침하고 남은 빈 문구를 다음 배치로 자동 처리합니다.
10. 새로고침 후 빈 문구가 없으면 미번역 카테고리(`findtype=untranslated`)의 첫 페이지로 이동해 남은 항목을 자동 번역합니다. 미번역 목록은 저장할 때마다 첫 페이지에서 다시 확인하며, 결과가 0개임을 확인한 뒤에만 전체 완료를 표시하고 작업을 종료합니다. 결과 수를 확인하지 못하거나 결과는 있는데 입력 가능한 항목이 없으면 완료 처리하지 않고 확인 실패를 표시합니다. Edge와 트레이는 계속 열어 둡니다.

현재 화면에 빈 번역란이 없어도 **자동 번역 시작**을 누르면 미번역 카테고리에서 남은 항목을 확인합니다.

패널의 모듈과 언어는 현재 주소를 실시간으로 따라갑니다. 실행 중 주소가 바뀌면 이전 모듈의 작업을 즉시 취소하고 새 주소 기준으로 초기화합니다. 실행 중에는 패널에서 중지할 수 있으며, 탭을 닫아도 실행 중인 Codex 프로세스 트리가 종료됩니다. 요청·응답·검증·최종 결과와 상태는 `runs/<module_id>/<batch_id>/`에 기록됩니다.

### 수동 흐름

1. **빈 문구를 Codex용으로 복사**를 누릅니다.
2. Codex 채팅에 그대로 붙여넣고 응답을 기다립니다.
3. Codex가 반환한 JSON 전체를 패널의 입력란에 붙여넣습니다.
4. **응답 검증**을 눌러 변수·태그·원문 해시·페이지 정보를 확인합니다.
5. 오류가 없다면 **빈 입력란 채우기**를 누릅니다.
6. 각 번역을 직접 검토한 다음 BGA에서 저장합니다.

이미 값이 있는 입력란은 항상 건너뜁니다. 페이지나 원문이 바뀌면 기존 응답을 적용하지 않고, 현재 페이지에서 다시 복사해야 합니다.

## 안전장치

- `en_US → ko_KR` 페이지에서만 활성화됩니다.
- `${...}`, `%name`, `%s`, `<...>` 변수와 태그가 달라지면 입력을 차단합니다.
- 숫자나 끝 문장부호가 달라지면 경고합니다.
- 응답의 모듈, 언어, 항목 ID, SHA-256 원문 해시를 확인합니다.
- 현재 페이지에서 읽기 전용으로 잠긴 BGA 번역만 검증된 참고 번역으로 수집하며, 모듈별로 최대 300개를 로컬 확장 저장소에 보관합니다.
- 신규 v2 가이드는 전체 원문 개수와 SHA-256, 공식 출처 URL, 용어별 `source_ids`와 `official_ko`/`derived_from_original` 근거를 요구합니다.
- 기본 화면 결과 수와 수집 화면 또는 순회별 원시 행 수의 불일치, 동일 ID의 내용 변경, 500페이지 초과, 청크 누락·순서 오류, 코퍼스 해시 불일치가 발생하면 부분 자료로 가이드를 만들지 않습니다. 실행 로그와 `bga-source-corpus-v2`에는 순회·페이지별 고유/신규/중복/누락 진단 및 정상 수렴/5회 합집합 fallback 여부를 남깁니다.
- 모듈 1542는 한국 공식 발매 용어를 우선 적용하고, 공식 용어와 다른 번역은 검증 오류로 차단합니다.
- 모듈 2841(킹 오브 더 다이스)은 게임 전용 용어집을 적용해 주사위·카드·지역명·캐릭터명을 배치마다 동일하게 유지합니다.
- 수동 채우기는 `input` 이벤트만 발생시키며 자동 저장하지 않습니다.
- 자동 저장은 원문 해시·빈 값·잠금 상태를 항목마다 다시 확인하고 검증 오류와 경고가 모두 0개일 때만 실행됩니다. 포커스 획득과 실제 입력값도 확인하며, BGA가 저장 후 행을 교체하거나 제거하면 최신 DOM을 다시 조회합니다.

## 테스트

Node.js 18 이상에서 다음 명령을 실행합니다.

```powershell
npm ci
npm test
```

네이티브 호스트 계약 테스트는 프로젝트 전용 SDK를 준비한 뒤 실행합니다.

```powershell
npm run test:host
npm run test:host-smoke
```

테스트는 수집 필터, 전체 코퍼스 청크·해시·pagination, v1/v2 가이드 검증, 프롬프트·JSON 계약, 번역 검증, 자동 저장 이벤트 순서·재시도, Native Messaging 프레이밍과 가짜 Codex 종단간 실행을 확인합니다.

## 현재 BGA UI와의 호환성

DOM 어댑터는 `textarea[id^="translated_"]` 입력란을 기준으로 같은 번역 행의 읽기 전용 textarea를 원문으로 연결합니다. 이전 BGA UI의 `.translation_block`, `.readonly_textarea` 구조도 함께 지원합니다. BGA가 페이지 구조를 변경해 안전하게 원문과 입력란을 연결할 수 없으면 패널이 진단 메시지를 표시하고 아무 입력도 수행하지 않습니다.