sodalive-android/docs/20260811_일본어_string_resource_반영/prd.md

# 일본어 string resource 반영 PRD

## 문서 정보

| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | `2026-08-11` |
| 최종 수정일 | `2026-08-11` |
| 대상 제품 | SodaLive Android 일본어 string resource |
| 작성자·결정권자 | 사용자, Sisyphus |
| 기준 CSV | `docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv` |
| 관련 구현 계획 | `docs/20260811_일본어_string_resource_반영/plan-task.md` |
| 관련 review | 없음 |

### 요구사항 상태

| 상태 | 의미 | 구현 처리 |
|---|---|---|
| 확정 | CSV와 사용자 결정으로 구현 기준이 정해짐 | `plan-task.md`의 Task와 완료 증거로 추적 |
| 미결 | 제품 문구 또는 매핑 판단이 더 필요함 | 임의 반영하지 않고 매핑 확정 단계에서 확인 |
| 제외 | 이번 작업에서 반영하지 않음 | Decision Log에 제외 이유 기록 |

## 1. Overview

`kr_jp_string_resource.csv`의 KR/JP 쌍을 기준으로 Android 일본어 리소스 `app/src/main/res/values-ja/strings.xml` 반영 범위를 확정한다. CSV에는 Android `string name` 키가 없으므로, 한국어 원문과 `app/src/main/res/values/strings.xml` 값을 대조해 resource key 매핑을 먼저 확정한 뒤 일본어 값을 반영한다.

## 2. Problem Statement

현재 일본어 리소스에는 CSV 기준 문구와 다른 번역, 미반영 번역, 오탈자 의심 항목이 섞여 있을 수 있다.

- CSV는 `KR`, `JP` 컬럼만 제공하고 Android resource key를 제공하지 않는다.
- `홈`, `콘텐츠`, `전체`, `라이브`, `댓글`, `삭제`처럼 같은 KR 문구가 여러 resource key에 반복된다.
- 기존 `values-ja/strings.xml` 값과 CSV 값이 다를 때 무조건 덮어쓰면 의도하지 않은 화면 문구가 바뀔 수 있다.

문제를 해결했다는 판단은 확정된 KR 문구/resource key 매핑에 한해 `values-ja/strings.xml`이 CSV JP 값을 반영하고, XML 리소스 빌드 검증이 통과하는 것으로 한다.

## 3. Goals

### 3.1 제품 목표

- CSV 기준 일본어 문구를 Android 일본어 리소스에 안전하게 반영한다.
- 중복 KR 문구는 resource key 단위로 매핑을 확정한 뒤 반영해 오반영을 막는다.
- 반영 대상, 제외 대상, 확인 필요 대상을 문서에 남겨 후속 검토가 가능하게 한다.

### 3.2 품질 목표

- `values-ja/strings.xml`의 XML escape, placeholder, 줄바꿈 형식을 Android resource 규칙에 맞게 유지한다.
- `%1$s`, `%1$d`, `%%`, `\n`, `@string/...` 참조를 깨지 않는다.
- 사용자가 명시적으로 요청하지 않았으므로 UI/계측 테스트, 기기 조작, 스크린샷 QA는 수행하지 않는다.

## 4. Non-Goals

- `app/src/main/res/values/strings.xml`의 한국어 원문 수정.
- `app/src/main/res/values-en/strings.xml` 수정.
- 레이아웃, 코드, 화면 흐름, API 계약 수정.
- CSV 자체 번역 품질을 임의로 재번역하거나 새 일본어 문구를 창작하는 작업.
- Android UI/계측 테스트 추가 또는 `connectedDebugAndroidTest` 실행.

## 5. Target Users and Permissions

| 사용자 | 목표 | 주요 작업 | 사용 환경 |
|---|---|---|---|
| 일본어 사용자 | 앱 화면에서 자연스럽고 CSV 기준과 일치하는 일본어 문구 확인 | 일본어 locale로 앱 사용 | Android |
| Android 개발자 | 확정된 매핑만 안전하게 리소스에 반영 | resource key 대조, XML 수정, 로컬 검증 | Android Gradle 프로젝트 |

권한 정책 변경은 없다. 인증, API, 데이터 소유권, 민감정보 저장 정책은 이번 범위 밖이다.

## 6. 핵심 처리 흐름

1. `kr_jp_string_resource.csv`의 KR/JP 행을 읽는다.
2. `app/src/main/res/values/strings.xml`에서 KR 문구와 일치하는 resource key 후보를 찾는다.
3. 같은 KR 문구가 여러 key에 매칭되면 모두 후보로 기록하고, 화면 맥락상 반영할 key를 확정한다.
4. `app/src/main/res/values-ja/strings.xml`의 기존 JP 값을 확인한다.
5. 확정된 key만 CSV JP 값으로 수정한다.
6. XML escape, placeholder, 줄바꿈, 빌드 리소스 검증을 실행한다.

## 7. 기능 요구사항

### 7.1 매핑 확정

| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `I18N-MAP-001` | 확정 | CSV 행은 resource key 없이 제공된 KR/JP 쌍으로 취급한다. | key 추정 없이 `values/strings.xml` 값과 일치하는 후보만 매핑 대상으로 삼는다. | `P1-T1` |
| `I18N-MAP-002` | 확정 | 동일 KR 문구가 여러 resource key에 있으면 자동 덮어쓰지 않는다. | 중복 후보는 `plan-task.md`의 후보 매핑/충돌 목록에 기록하고 확정된 key만 반영한다. | `P1-T1`, `P1-T2` |
| `I18N-MAP-003` | 확정 | CSV JP와 기존 JP가 다른 항목은 변경 후보로 분리한다. | 변경 전 기존 값, CSV 값, 반영 결정이 기록된다. | `P1-T2` |
| `I18N-MAP-004` | 확정 | CSV JP의 오탈자 의심 항목은 임의 수정하지 않는다. | 예: `しいシリーズを見つけましょう！`처럼 의심되는 값은 확인 필요로 남긴다. | `P1-T2` |

### 7.2 리소스 반영

| ID | 상태 | 요구사항 | 수용 기준 | 계획 연결 |
|---|---|---|---|---|
| `I18N-RES-001` | 확정 | 반영 대상은 `app/src/main/res/values-ja/strings.xml`로 한정한다. | 한국어, 영어, layout, Kotlin 파일 변경 없이 일본어 리소스만 수정한다. | `P2-T1` |
| `I18N-RES-002` | 확정 | Android string placeholder 형식을 보존한다. | KR의 `%1$s`, `%1$d`, `%%`에 대응되는 placeholder가 JP에도 보존된다. | `P2-T1`, `P2-GATE` |
| `I18N-RES-003` | 확정 | CSV 줄바꿈은 Android XML에서 `\n`으로 표현한다. | 실제 줄바꿈 또는 CSV quote가 XML을 깨지 않는다. | `P2-T1`, `P2-GATE` |
| `I18N-RES-004` | 확정 | `@string/...` 참조 값은 CSV 직접 문구와 매칭되더라도 참조 의도를 먼저 확인한다. | 참조를 문자열로 풀어야 하는 근거가 없으면 기존 참조를 보존한다. | `P1-T2`, `P2-T1` |

## 8. API 계약

API 변경은 없다. 서버 계약, request/response, endpoint, 인증 header는 이번 범위 밖이다.

## 9. 보안과 데이터 취급

- 비밀값, 토큰, URL, 사용자 개인정보를 문서나 로그에 추가하지 않는다.
- `BuildConfig` 값은 출력, 로그, Toast, 문서 예시에 포함하지 않는다.
- CSV와 resource XML 외 외부 데이터 소스는 사용하지 않는다.

## 10. 성능과 품질 요구사항

- 신규 dependency를 추가하지 않는다.
- 리소스 XML 파싱과 빌드가 통과해야 한다.
- 기본 검증 명령은 `./gradlew :app:assembleDebug`, 필요 시 `./gradlew :app:lintDebug`다.
- 로직 변경이 없으므로 신규 unit test는 기본적으로 작성하지 않는다.

## 11. 성공 기준

### 11.1 기능 수용 기준

- [ ] CSV KR/JP 행 중 `values/strings.xml`과 매칭되는 후보가 resource key 단위로 식별된다. (`I18N-MAP-001`)
- [ ] 중복 KR 문구와 기존 JP 충돌 항목이 반영/보류/제외 중 하나로 분류된다. (`I18N-MAP-002`, `I18N-MAP-003`)
- [ ] 확정된 key만 `values-ja/strings.xml`에 반영된다. (`I18N-RES-001`)
- [ ] Android resource placeholder와 줄바꿈 형식이 보존된다. (`I18N-RES-002`, `I18N-RES-003`)

### 11.2 추적성 완료 기준

- [ ] 모든 확정 요구사항이 `plan-task.md`의 Task와 완료 증거로 연결된다.
- [ ] 확인 필요 문구는 임의 반영하지 않고 Decision Log 또는 발견된 문제에 남긴다.
- [ ] 제외 항목은 제외 이유와 후속 조건을 기록한다.

## 12. Open Questions

| ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 시점 | 영향 Goal |
|---|---|---|---|---|---|---|
| `OQ-001` | 확정 | CSV에 key가 없을 때 반영 정책 | 매핑표 먼저 확정 후 확정 key만 반영 | 사용자 | 2026-08-11 | `P1-T1`, `P1-T2` |
| `OQ-002` | 미결 | CSV JP 오탈자 의심 항목을 그대로 반영할지 제품 문구로 보정할지 | 오탈자 의심 항목은 보류하고 사용자 확인 후 반영 | 사용자 | `P1-T2` 완료 전 | `P2-T1` |

## 13. 요구사항 추적표

| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---:|---|---|---|
| `I18N-MAP-001~004` | 1 | `P1-T1`, `P1-T2`, `P1-GATE` | CSV/resource 대조, XML 후보 목록 확인 | 사용자 매핑 승인 |
| `I18N-RES-001~004` | 2 | `P2-T1`, `P2-GATE` | `./gradlew :app:assembleDebug`, 필요 시 `./gradlew :app:lintDebug` | 일본어 locale 화면 확인은 사용자 명시 요청 시 별도 수행 |

## 14. Decision Log

| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
|---|---|---|---|---|---|
| 2026-08-11 | `DEC-001` | 확정 | CSV KR/JP 쌍은 resource key 매핑표를 먼저 확정한 뒤 반영한다. | CSV에 key가 없고 동일 KR 문구가 여러 resource key에 반복된다. | `I18N-MAP-001~003`, `P1-T1`, `P1-T2` |
| 2026-08-11 | `DEC-002` | 확정 | 이번 요청에서는 PRD와 계획문서만 생성하고 실제 string resource는 수정하지 않는다. | 사용자 요청: “모호한 것은 물어보고 prd와 계획문서만 생성한다.” | 전체 |
| 2026-08-11 | `DEC-003` | 확정 | 문서는 CSV 파일이 있는 `docs/20260811_일본어_string_resource_반영/` 폴더에 생성한다. | 사용자 요청: “문서 생성은 csv파일이 있는 폴더에 생성한다.” | 전체 |

## 15. 변경 관리

요구사항 변경 시 다음을 확인한다.

- [ ] Decision Log에 변경 이유와 날짜를 기록했다.
- [ ] 관련 요구사항 상태, 본문, 수용 기준을 갱신했다.
- [ ] `plan-task.md`의 범위, Files, 체크박스, 완료 증거를 코드 변경 전에 갱신했다.
- [ ] 기존 Progress, 검증 기록, Decision Log를 삭제하거나 덮어쓰지 않았다.