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

일본어 string resource 반영 Goal 실행형 구현 계획

문서 항목	내용
상태	계획 작성 완료
작성일	2026-08-11
요구사항 기준	docs/20260811_일본어_string_resource_반영/prd.md
API 기준	API 변경 없음
현재 Phase	Phase 1 매핑 확정 대기
현재 활성 Goal	없음

목표

kr_jp_string_resource.csv의 일본어 문구를 resource key 단위로 안전하게 확정한 뒤 Android values-ja/strings.xml에 최소 반영한다.

현재 상태

Phase	상태	완료 Task	활성/다음 Goal	차단 또는 남은 조건
1	대기	0/2	P1-T1	확정 매핑표 작성 필요
2	대기	0/1	P2-T1	P1-GATE 완료 필요

• 동시에 하나의 미완료 goal만 운용한다.
• 완료된 Task와 검증 기록은 되돌리거나 삭제하지 않는다.
• 후속 수정은 기존 완료 Task를 다시 열지 않고 신규 회귀 수정 Task로 추가한다.

범위

포함

• docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv 기준 KR/JP 쌍 분석.
• app/src/main/res/values/strings.xml의 KR 값과 resource key 후보 대조.
• app/src/main/res/values-ja/strings.xml의 기존 JP 값과 CSV JP 값 차이 확인.
• 확정된 key에 한해 app/src/main/res/values-ja/strings.xml 수정.
• Android resource XML 빌드 검증.

제외

• app/src/main/res/values/strings.xml 한국어 원문 수정.
• app/src/main/res/values-en/strings.xml 영어 리소스 수정.
• layout, Kotlin, API, navigation, ViewModel 변경.
• 신규 dependency 추가.
• app/src/androidTest, 기기·에뮬레이터 조작, 스크린샷 QA.
• CSV JP 문구를 임의 재번역하는 작업.

기술적 제약

• 기술 스택: Android Gradle 프로젝트, XML string resource.
• 리소스 파일: app/src/main/res/values/strings.xml, app/src/main/res/values-ja/strings.xml.
• 기준 CSV: docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv.
• CSV에는 resource key가 없으므로 한국어 값이 정확히 일치하는 후보만 자동 매핑 대상으로 삼는다.
• 같은 KR 문구가 여러 resource key에 있으면 자동 덮어쓰지 않고 후보 목록에서 확정한다.
• %1$s, %1$d, %%, \n, XML escape, @string/... 참조를 깨지 않는다.
• 로직 변경이 없으므로 신규 unit test는 기본 작성하지 않는다.
• 검증은 ./gradlew :app:assembleDebug를 기본으로 하고, 리소스 lint 확인이 필요하면 ./gradlew :app:lintDebug를 추가한다.

Task TDD 작성 규칙

이번 계획의 Phase 1은 read-only 대조와 문서 확정이므로 TDD 예외를 적용한다. Phase 2는 XML 리소스 수정 작업이며 로직 unit test 대상이 아니므로 RED/GREEN 테스트 대신 XML 빌드 검증을 완료 증거로 사용한다.

Phase 1 매핑 확정

Phase 결과: CSV KR/JP 행이 resource key 후보, 반영 대상, 보류 대상, 제외 대상으로 분류된다.

선행조건: prd.md의 DEC-001 확정.

Phase 완료 조건: P1-T1, P1-T2, P1-GATE 완료, 검증 기록 누적.

구현 항목

Task 1.1 CSV와 한국어 resource 후보 대조

Goal 실행 P1-T1: CSV KR 문구와 values/strings.xml의 한국어 resource key 후보를 대조한다.

• 시작 조건: kr_jp_string_resource.csv, app/src/main/res/values/strings.xml 존재.
• 완료 증거: 후보 대조 결과가 plan-task.md의 Progress에 기록되고, 중복 KR 문구가 별도 표시된다.
• 범위 밖: values-ja/strings.xml 수정, CSV 문구 수정.
• TDD 예외 사유: production 동작을 변경하지 않는 read-only 대조 Task다.
• 대체 검증 방법: CSV KR 값과 values/strings.xml string body를 대조하고, exact match 수와 중복/미매칭 예시를 Progress에 기록한다.

Files:

• Read: docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv
• Read: app/src/main/res/values/strings.xml
• Modify: docs/20260811_일본어_string_resource_반영/plan-task.md

Interfaces:

• Consumes: CSV KR, JP 컬럼과 Android <string name="...">...</string> 값.

• Produces: P1-T2가 사용할 KR 문구별 resource key 후보 목록.

• CSV의 KR, JP 행을 파싱한다.

• values/strings.xml의 <string> 값을 key와 함께 추출한다.

• CSV KR과 한국어 resource 값을 exact match로 대조한다.

• 같은 KR 문구가 여러 key에 매칭되는 항목을 중복 후보로 표시한다.

• 매칭되지 않은 CSV KR 행은 신규 key 추정 없이 미매칭 후보로 기록한다.

• Progress에 exact match 수, 중복 후보 수, 미매칭 후보 수와 대표 예시를 남긴다.

Task 1.2 일본어 기존값 충돌과 보류 항목 확정

Goal 실행 P1-T2: values-ja/strings.xml의 기존 JP 값과 CSV JP 값을 대조해 반영/보류/제외 결정을 확정한다.

• 시작 조건: P1-T1 완료.
• 완료 증거: 확정 반영 목록과 보류 목록이 plan-task.md Progress 또는 Decision Log에 기록된다.
• 범위 밖: 확정되지 않은 key 반영, 일본어 재번역.
• TDD 예외 사유: production 동작을 변경하지 않는 read-only 대조와 의사결정 Task다.
• 대체 검증 방법: 기존 JP 값, CSV JP 값, placeholder 차이, 줄바꿈 차이, 오탈자 의심 항목을 대조한다.

Files:

• Read: app/src/main/res/values-ja/strings.xml
• Modify: docs/20260811_일본어_string_resource_반영/plan-task.md

Interfaces:

• Consumes: P1-T1의 resource key 후보 목록.

• Produces: P2-T1이 수정할 확정 key/value 목록.

• 후보 key마다 기존 values-ja/strings.xml 값을 확인한다.

• CSV JP와 기존 JP가 같은 항목은 변경 없음으로 분류한다.

• CSV JP와 기존 JP가 다른 항목은 변경 후보로 분류한다.

• KR placeholder와 JP placeholder가 다른 항목은 보류한다.

• CSV JP 오탈자 의심 항목은 보류하고 Decision Log에 사용자 확인 필요로 남긴다.

• @string/... 참조는 참조를 풀어야 하는 명확한 근거가 없으면 보류한다.

• 반영 대상 key, 보류 대상 key, 제외 대상 key를 Progress에 기록한다.

완료 조건

• P1-T1, P1-T2의 체크박스와 완료 증거가 모두 충족됐다.
• 확정 반영 대상 key 목록이 존재한다.
• 보류 항목은 이유와 후속 결정 주체가 기록됐다.
• 확정되지 않은 항목을 Phase 2에 넘기지 않았다.

검증 방법

Phase 1 Gate

Goal 실행 P1-GATE: 매핑 결과가 PRD 정책과 충돌하지 않는지 최종 판정한다.

• 시작 조건: P1-T1, P1-T2 완료.
• 완료 증거: 아래 대조 기준 통과와 Progress 기록.
• 범위 밖: Gate 통과를 위한 임의 번역, CSV 수정, resource 수정.

검증 기준:

• 확정 반영 목록의 모든 key는 values/strings.xml에 존재한다.
• 확정 반영 목록의 모든 key는 values-ja/strings.xml에 존재하거나 신규 추가 필요로 명시됐다.
• 확정 반영 목록의 JP 값은 CSV JP에서 온 값이다.
• placeholder와 줄바꿈 형식이 Android XML에 맞게 표현될 수 있다.
• 보류 항목은 Phase 2 수정 목록에서 제외됐다.

Phase 2 일본어 resource 반영

Phase 결과: 확정된 key만 values-ja/strings.xml에 반영되고 Android resource 빌드가 통과한다.

선행조건: P1-GATE 완료.

Phase 완료 조건: P2-T1, P2-GATE 완료, 검증 기록 누적.

구현 항목

Task 2.1 확정 key를 values-ja에 반영

Goal 실행 P2-T1: Phase 1에서 확정된 key만 app/src/main/res/values-ja/strings.xml에 반영한다.

• 시작 조건: P1-GATE 완료와 확정 반영 key 목록 존재.
• 완료 증거: values-ja/strings.xml diff가 확정 key에만 한정되고 XML 빌드 검증이 통과한다.
• 범위 밖: 한국어/영어 리소스 수정, 확정되지 않은 보류 항목 반영, 레이아웃/코드 수정.
• TDD 예외 사유: Android XML string resource 수정이며 로직 unit test 대상이 아니다.
• 대체 검증 방법: resource XML diff 검토, placeholder 대조, Gradle assemble/lint 명령 실행.

Files:

• Modify: app/src/main/res/values-ja/strings.xml
• Reference: docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv
• Modify: docs/20260811_일본어_string_resource_반영/plan-task.md

Interfaces:

• Consumes: P1-GATE에서 승인된 key/value 목록.

• Produces: Android 일본어 locale에서 사용할 확정 JP string resource.

• RED 대체 확인: 수정 전 ./gradlew :app:assembleDebug를 실행해 baseline resource 상태를 확인한다.

• GREEN: 확정 key만 values-ja/strings.xml에서 CSV JP 값으로 수정한다.

• GREEN 확인: ./gradlew :app:assembleDebug를 실행해 Android resource 빌드가 통과하는지 확인한다.

• REFACTOR: 이번 Task가 만든 XML escape, placeholder, 줄바꿈 문제만 정리하고 ./gradlew :app:assembleDebug를 다시 실행한다.

• 필요 시 ./gradlew :app:lintDebug를 실행하고 결과를 Progress에 기록한다.

완료 조건

• values-ja/strings.xml diff가 확정 key에만 한정됐다.
• %1$s, %1$d, %%, \n, XML escape가 깨지지 않았다.
• 보류 항목은 반영되지 않았다.
• Gradle resource 빌드 검증 결과가 Progress에 기록됐다.

검증 방법

Phase 2 Gate

Goal 실행 P2-GATE: 일본어 resource 반영 결과와 회귀 위험을 최종 판정한다.

• 시작 조건: P2-T1 완료.
• 완료 증거: 아래 명령과 Expected 통과, Progress에 실제 결과 누적.
• 범위 밖: Gate 실패와 무관한 기능 수정, UI/계측 테스트 실행.

./gradlew :app:assembleDebug

Expected: exit code 0, Android resource XML 파싱 성공, debug APK assemble 성공.

필요 시 추가 검증:

./gradlew :app:lintDebug

Expected: exit code 0 또는 이번 resource 변경과 무관한 기존 lint 이슈만 보고.

실행 순서와 의존성

순서	Goal	선행조건	병행 가능	차단 시 다음 행동
1	P1-T1	없음	아니요	CSV 또는 한국어 resource 형식 문제를 Progress에 기록
2	P1-T2	P1-T1	아니요	보류 항목을 사용자 확인 대상으로 분리
3	P1-GATE	Phase 1 Task 전체	아니요	확정되지 않은 항목을 Phase 2에서 제외
4	P2-T1	P1-GATE	아니요	실패 key를 보류로 되돌리고 Decision Log에 기록
5	P2-GATE	P2-T1	아니요	실패 원인 key만 회귀 수정 Task로 분리

P1-T1 -> P1-T2 -> P1-GATE -> P2-T1 -> P2-GATE

변경 금지 항목

• 확정되지 않은 CSV 행을 resource key에 임의 매핑하지 않는다.
• 같은 KR 문구가 여러 key에 있을 때 전체를 자동 덮어쓰지 않는다.
• CSV JP 문구를 임의 재번역하지 않는다.
• values/strings.xml, values-en/strings.xml, layout, Kotlin 파일을 수정하지 않는다.
• 신규 dependency를 추가하지 않는다.
• test를 삭제, skip, 완화하지 않는다.
• 기기·에뮬레이터 UI 조작, 스크린샷 QA, connectedDebugAndroidTest를 실행하지 않는다.

의사결정 및 중단 규칙

• PRD와 plan-task가 충돌하면 PRD Decision Log를 우선하고 plan-task를 먼저 갱신한다.
• CSV JP에 오탈자 의심이 있으면 임의 수정 또는 반영하지 않고 보류한다.
• placeholder가 맞지 않으면 해당 key는 보류하고 사용자 확인 대상으로 남긴다.
• values-ja/strings.xml에 key가 없으면 신규 추가 여부를 사용자에게 확인한다.
• Gradle 검증 실패가 발생하면 실패한 resource key만 확인하고 관련 없는 기능 수정은 하지 않는다.

Progress

기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.

문서 작성 1차 실행 — 2026-08-11

• 상태: 완료
• 무엇을: PRD와 계획문서 초안을 작성했다.
• 왜: 사용자가 CSV 기반 일본어 string resource 반영 전에 모호한 사항을 확인하고 PRD/계획문서만 생성하라고 요청했다.
• 어떻게:
  • docs/sample/sample-prd.md 확인 — PRD 구조 확인.
  • docs/sample/sample-plan-task.md 확인 — plan-task 구조 확인.
  • docs/agent-guides/work-plan-docs.md 확인 — 문서 위치와 작성 규칙 확인.
  • docs/agent-guides/build-test-style.md 확인 — Android Gradle 검증 명령 확인.
  • app/src/main/res/values/strings.xml, app/src/main/res/values-ja/strings.xml 일부 확인 — CSV에 key가 없고 동일 KR 문구가 반복되는 위험 확인.
• 남은 항목: 실제 매핑 확정과 resource 반영은 아직 수행하지 않음.
• 다음 행동: 사용자가 구현을 요청하면 P1-T1부터 실행한다.

Decision Log

날짜	ID	상태	결정	근거	영향 Goal/문서
2026-08-11	DEC-001	확정	CSV KR/JP 쌍은 resource key 매핑표를 먼저 확정한 뒤 반영한다.	CSV에는 string name이 없고 중복 KR 문구가 존재한다.	P1-T1, P1-T2, P2-T1
2026-08-11	DEC-002	확정	이번 실행에서는 prd.md, plan-task.md만 생성하고 resource XML은 수정하지 않는다.	사용자 요청 범위가 문서 생성으로 한정됐다.	전체

발견된 문제

ID	심각도	상태	발견 내용	영향 Goal	처리 계획
ISSUE-001	Medium	후보	CSV에 resource key가 없어 동일 KR 문구를 자동 매핑하면 오반영 위험이 있다.	P1-T1	exact match 후보와 중복 후보를 분리한다.
ISSUE-002	Low	후보	기존 values-ja/strings.xml에 フォロー를解除처럼 혼합 언어 의심 문구가 있다.	P1-T2	CSV 매핑 후보와 일치하면 변경 후보로 분류한다.
ISSUE-003	Low	후보	CSV JP에 しいシリーズを見つけましょう！처럼 오탈자 의심 문구가 있다.	P1-T2	사용자 확인 전 반영하지 않는다.

Verification Log

• 2026-08-11 문서 생성 검증: prd.md, plan-task.md를 CSV 파일이 있는 docs/20260811_일본어_string_resource_반영/ 폴더에 생성했다. 코드와 resource XML은 수정하지 않았다.

최종 보고 형식

구현 결과: <완료한 Phase와 resource 반영 범위>

- 변경: <수정한 resource key와 파일>
- 결정: <Decision Log ID와 내용>
- 검증:
  - `<실행 명령>` — <성공/실패와 핵심 결과>
- 남은 항목: <보류된 문구 또는 없음>
- 문서: <갱신한 PRD/plan-task 경로>