13 KiB
13 KiB
일본어 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_반영/resource-mapping.md |
| 관련 구현 계획 | 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-mapping.md에 저장하고 resource key 매핑을 먼저 확정한 뒤 일본어 값을 반영한다. {{...}}, {...}, n%처럼 앱에서 치환되는 문구는 Android placeholder 또는 suffix resource와 대응되는 경우 후보로 포함한다.
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에 매칭되면 모두
resource-mapping.md에 후보로 기록하고, 기존 JP가 CSV JP와 다르면 CSV JP를 우선 반영한다. 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에 있으면 모든 후보를 기록하고 CSV JP를 우선한다. | 중복 후보 중 기존 JP가 CSV JP와 다르면 해당 key에 CSV JP를 반영한다. | P1-T1, P1-T2, P2-T1 |
I18N-MAP-003 |
확정 | CSV JP와 기존 JP가 다른 항목은 변경 후보로 분리한다. | 변경 전 기존 값, CSV 값, 반영 결정이 resource-mapping.md에 기록된다. |
P1-T2 |
I18N-MAP-004 |
확정 | CSV JP의 오탈자 의심 항목은 제품 문구를 임의 보정하지 않는다. | KR resource key가 있으면 CSV JP를 그대로 반영하고 최종 리포트에 확인 필요로 기록한다. KR resource key가 없으면 반영하지 않는다. | P1-T2, P2-T1 |
I18N-MAP-005 |
확정 | values/strings.xml에 exact 또는 placeholder/suffix 대응 한국어 리소스가 없으면 반영하지 않는다. |
해당 CSV 행은 신규 key 추정 없이 resource-mapping.md에서 제외로 분류한다. |
P1-T2, P1-GATE |
I18N-MAP-006 |
확정 | CSV의 {{...}}, {...}, n% 치환 문구는 앱 내 변경 가능한 리소스로 고려한다. |
Android %1$s, %1$d, suffix resource와 안전하게 대응되는 경우 후보로 기록하고 Android 형식 값으로 반영한다. |
P1-T2, P2-T1 |
I18N-MAP-007 |
확정 | 매핑표의 <br>은 표시용이며 XML에 그대로 반영하지 않는다. |
values-ja/strings.xml에는 줄바꿈을 \n으로 저장하고 literal <br>이 없어야 한다. |
P2-T1, P2-GATE |
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 충돌 항목이
resource-mapping.md에서 반영/보류/제외 중 하나로 분류된다. (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 오탈자 의심 항목을 그대로 반영할지 제품 문구로 보정할지 | KR resource key가 있으면 CSV JP 그대로 반영하고 최종 리포트에 기록 | 사용자 | 2026-08-11 | P2-T1 |
OQ-003 |
확정 | 한국어 리소스가 없는 CSV 행을 신규 key로 추가할지 여부 | exact 또는 placeholder/suffix 대응 key가 없으면 신규 key를 만들지 않고 제외 | 사용자 | 2026-08-11 | P1-T2, P1-GATE |
OQ-004 |
확정 | 중복 KR 후보의 기존 JP가 CSV JP와 다를 때 처리 | CSV JP 우선 반영 | 사용자 | 2026-08-11 | P2-T1 |
OQ-005 |
확정 | 매핑표 <br>의 XML 반영 방식 |
literal <br>이 아니라 \n 줄바꿈으로 반영 |
사용자 | 2026-08-11 | P2-T1, P2-GATE |
13. 요구사항 추적표
| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---|---|---|---|
I18N-MAP-001~007 |
1 | P1-T1, P1-T2, P1-GATE |
resource-mapping.md 후보 목록 확인 |
사용자 매핑 승인 |
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파일이 있는 폴더에 생성한다.” | 전체 |
| 2026-08-11 | DEC-004 |
확정 | 매핑표는 resource-mapping.md 별도 파일로 생성한다. |
매핑 행이 많고 반영/보류/제외 검토가 필요해 plan-task.md Progress에만 누적하면 추적성이 낮다. |
I18N-MAP-002~003, P1-T1, P1-T2 |
| 2026-08-11 | DEC-005 |
확정 | 한국어 리소스가 없는 CSV 행은 반영하지 않고 제외로 분류한다. |
사용자 지시: “한국어 리소스가 없는 것은 반영하지 않는다.” | I18N-MAP-005, P1-T2, P1-GATE |
| 2026-08-11 | DEC-006 |
확정 | JP 오탈자 의심 항목은 CSV 값을 그대로 반영하고 최종 리포트에 확인 필요로 기록한다. | 사용자 지시: “JP 오탈자로 의심되는 것은 우선 그대로 반영하고 최종 리포트에 기록” | I18N-MAP-004, P2-T1 |
| 2026-08-11 | DEC-007 |
확정 | {{...}}, {...}, n% 치환 문구는 Android placeholder/suffix 대응 후보로 재확인한다. |
사용자 지시: “{{}} 형태로 들어가 있는 것은 앱 내에서 변경할 수 있는 리소스” | I18N-MAP-006, P1-T2, P2-T1 |
| 2026-08-11 | DEC-008 |
확정 | 중복 KR 후보의 JP가 다르면 CSV JP를 우선 반영한다. | 사용자 지시: “중복되는 것 중 JP가 다르게 적용되어 있는 것은 csv JP를 우선 반영” | I18N-MAP-002, P2-T1 |
| 2026-08-11 | DEC-009 |
확정 | 매핑표 <br>은 XML에 literal로 쓰지 않고 \n으로 반영한다. |
사용자 지시: “ 은 그대로 반영하는 것이 아니라 줄바꿈으로 반영” |
I18N-MAP-007, P2-T1, P2-GATE |
15. 변경 관리
요구사항 변경 시 다음을 확인한다.
- Decision Log에 변경 이유와 날짜를 기록했다.
- 관련 요구사항 상태, 본문, 수용 기준을 갱신했다.
plan-task.md의 범위, Files, 체크박스, 완료 증거를 코드 변경 전에 갱신했다.- 기존 Progress, 검증 기록, Decision Log를 삭제하거나 덮어쓰지 않았다.