일본어 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. 핵심 처리 흐름
kr_jp_string_resource.csv의 KR/JP 행을 읽는다.app/src/main/res/values/strings.xml에서 KR 문구와 일치하는 resource key 후보를 찾는다.- 같은 KR 문구가 여러 key에 매칭되면 모두 후보로 기록하고, 화면 맥락상 반영할 key를 확정한다.
app/src/main/res/values-ja/strings.xml의 기존 JP 값을 확인한다.- 확정된 key만 CSV JP 값으로 수정한다.
- 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 기능 수용 기준
11.2 추적성 완료 기준
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. 변경 관리
요구사항 변경 시 다음을 확인한다.
