18 KiB
18 KiB
일본어 string_resource 반영 PRD
문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 구현 기준 확정 |
| 작성일 | 2026-08-11 |
| 최종 수정일 | 2026-08-11 |
| 대상 제품 | SodaLive iOS 일본어 문자열 리소스 |
| 작성자·결정권자 | 작성자: Sisyphus / 결정권자: 제품·iOS 담당자 |
| 관련 API Contract | 해당 없음 |
| 관련 구현 계획 | docs/20260811_일본어_string_resource_반영/plan-task.md |
| 관련 원본 | docs/20260811_일본어_string_resource_반영/kr_jp_string_resource.csv |
| 관련 review | 없음 |
요구사항 상태
| 상태 | 의미 | 구현 처리 |
|---|---|---|
| 확정 | CSV와 현재 iOS 문자열 구조만으로 구현 기준을 정할 수 있음 | plan-task.md의 Task와 완료 증거로 추적 |
| 미결 | 제품·번역·키 매핑 결정이 더 필요함 | Open Questions에 기록하고 임의 구현 금지 |
| 제외 | 이번 작업에서 구현하지 않음 | Non-Goals와 Decision Log에 기록 |
문서 우선순위와 갱신 순서
- CSV의 KR/JP 원문은 이 PRD의 입력 기준으로 사용한다.
SodaLive/Sources/I18n/I18n.swift의 기존pick(ko:en:ja:)구조를 우선 유지한다.{{키워드}}의 오디오처럼{{...}},{...},n%,n위,0:00형태로 런타임 값이 들어가는 CSV 문구는 Swift interpolation 문구와 정규화 매칭한다.- CSV 셀 안의 실제 줄바꿈과 HTML br 표기는 문자열 그대로 반영하지 않고 Swift 문자열 줄바꿈 escape
\n으로 변환한다. - CSV와 구현 구조가 충돌하면 Decision Log → 요구사항 →
plan-task.md순서로 갱신한다. - 확정된 결정 밖의 추정 번역, 추정 영어 문구, 추정 키는 구현하지 않는다.
1. Overview
kr_jp_string_resource.csv에 정리된 한국어-일본어 문구를 SodaLive iOS 앱의 문자열 리소스에 반영해 일본어 환경에서 사용자 노출 문구를 최신 번역으로 표시한다. 현재 앱은 SodaLive/Sources/I18n/I18n.swift의 하드코딩 맵과 pick(ko:en:ja:) 헬퍼를 통해 언어별 문자열을 선택한다. 이 작업은 코드 구현 전 PRD와 실행 계획만 작성하며, 실제 I18n.swift 수정은 후속 승인 후 진행한다.
2. Problem Statement
현재 사용자는 다음 문제를 겪는다.
- 일본어 번역 CSV가 앱 문자열 리소스에 아직 반영되지 않아 일본어 UI 문구가 최신 번역 기준과 다를 수 있다.
- CSV에는 개행 문구, placeholder 문구, 오탈자 후보가 섞여 있어 임의 치환 시 포맷 깨짐이나 잘못된 일본어 노출 위험이 있다.
I18n.swift는ko,en,ja를 함께 요구하므로 CSV에 없는 영어 문구를 임의 생성하면 기존 영어 UX가 변할 수 있다.
문제를 해결했다는 판단은 CSV의 확정 가능한 JP 값이 I18n.swift에 반영되고, 일본어 선택 시 해당 문구가 표시되며, 빌드가 성공하는 것으로 한다.
3. Goals
3.1 제품 목표
- CSV 데이터 242행 중 기존 한국어 리소스가 확인된 KR/JP 문구만 iOS 일본어 문자열에 반영한다.
- 기존
I18n.swift에 동일 KR 문구가 있거나 placeholder 정규화 후 같은 문구로 판정되는 항목은 기존en값을 유지하고ja값만 CSV 기준으로 갱신한다. - 동일 KR 문구가 없는 CSV 항목은 신규 리소스로 추가하지 않는다.
- 개행 33행과 placeholder 유사 12행은 기존 한국어 리소스가 있는 경우에만 CSV 셀 안의 실제 줄바꿈을 Swift 문자열
\n으로 변환하고 함수 인자 순서를 보존해 반영한다. - CSV에 HTML br 표기가 있으면 literal이 아니라 Swift 문자열
\n으로 변환해 반영한다. - 같은 KR 또는 같은 정규화 KR이 여러
I18n항목에 중복되어 있고 기존 JP가 서로 다르면 CSV JP를 우선해 같은 값으로 반영한다.
3.2 UX 목표
- 일본어 환경에서 홈, 콘텐츠, 대화, 마이페이지, 인증, 구매, 보관함 등 CSV가 포함한 주요 화면 문구가 자연스럽게 표시된다.
- placeholder가 포함된 문구는 실제 값 삽입 후 일본어 문장 순서가 깨지지 않는다.
- CSV의
しいシリーズ오탈자 후보는新しいシリーズ로 보정해 반영한다.
4. Non-Goals
- 이번 요청에서는 코드, 리소스, Xcode 프로젝트 설정을 수정하지 않는다.
- String Catalog(
.xcstrings) 도입이나I18n.swift구조 개편은 하지 않는다. - CSV에 없는 영어 번역을 새로 작성하지 않는다.
- 기존 한국어 리소스가 없는 CSV 항목을 신규 리소스로 추가하지 않는다.
- 서버 API, CMS, 백엔드 번역 리소스는 변경하지 않는다.
- 일본어 폰트, 레이아웃, 줄바꿈 UI 디자인 조정은 이 작업의 범위가 아니다.
5. Target Users and Permissions
| 사용자 | 목표 | 주요 작업 | 사용 환경 |
|---|---|---|---|
| 일본어 앱 사용자 | 일본어 UI 문구를 최신 번역으로 확인 | 앱 탐색, 콘텐츠 소비, 대화, 구매, 인증 | iOS 앱, 언어 설정 ja 또는 시스템 일본어 |
| iOS 개발자 | CSV 기준으로 안전하게 문자열 반영 | 문자열 매핑, 빌드 검증, 수동 QA | Xcode, SodaLive.xcworkspace |
| 제품·번역 담당자 | 확정된 일본어 반영 범위 확인 | 오탈자 보정과 제외 기준 승인 | PRD/계획문서 리뷰 |
권한 요구사항은 해당 없음이다. 단, 인증/구매/성인 관련 문구는 실제 기능 동작을 바꾸지 않고 표시 문자열만 바꾼다.
6. 핵심 사용자 흐름
- 사용자가 앱 언어를 일본어로 설정하거나 시스템 언어가 일본어인 상태에서 앱을 실행한다.
- 앱은
LanguageHeaderProvider.current결과가ja일 때I18n.pick의 일본어 문자열을 선택한다. - 사용자는 홈, 콘텐츠, 대화, 마이페이지, 인증/구매 화면에서 CSV 기준 일본어 문구를 본다.
- placeholder 문구는 실제 크리에이터명, 이메일, 요일, 퍼센트 등 런타임 값과 함께 자연스럽게 표시된다.
7. 정보 구조와 라우팅
별도 route 변경은 없다. 문자열 반영 대상은 기존 화면과 모듈에 종속된다.
SodaLive/Sources/I18n/I18n.swift
I18n.Module.ScreenOrDomain.Role
역할 중심 키 이름을 유지한다. 이번 작업에서는 기존 한국어 리소스가 없는 CSV 항목의 신규 키를 추가하지 않으며, 공통 네임스페이스 승격도 하지 않는다.
8. 기능 요구사항
8.1 CSV 입력과 매핑
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
JSR-001 |
확정 | kr_jp_string_resource.csv의 KR, JP 컬럼을 입력 기준으로 사용한다. |
CSV가 242개 데이터 행, KR 누락 0건, JP 누락 0건으로 파싱된다. | P1-T1 |
JSR-002 |
확정 | 기존 I18n.swift에 동일 KR literal이 있거나 placeholder 정규화 후 매칭되는 항목은 ja 값만 CSV 기준으로 갱신한다. |
기존 en 값과 호출부는 변경되지 않는다. 현재 스캔 기준 exact 103행, placeholder 정규화 추가 0행으로 총 103행이 매핑 후보다. |
P1-T2, P2-T1 |
JSR-003 |
제외 | 동일 KR literal 또는 placeholder 정규화 매칭이 없는 139개 CSV 항목은 신규 키로 추가하지 않는다. | 기존 한국어 리소스가 없는 항목은 I18n.swift와 호출부를 변경하지 않는다. |
P1-T3, P2-T2 |
JSR-004 |
확정 | CSV 셀 안의 실제 줄바꿈과 HTML br 표기는 Swift 문자열 줄바꿈 escape \n으로 변환한다. |
일본어 \n 위치가 CSV와 동일하거나 제품 승인된 위치로 반영되며, HTML br 표기가 앱 문자열에 그대로 남지 않는다. |
P2-T1 |
JSR-005 |
확정 | placeholder 유사 12개 문구는 앱 내에서 변경 가능한 리소스 후보로 보고 Swift interpolation과 정규화 매칭한다. | 정규화 매칭되는 기존 리소스는 Swift 함수 인자 순서를 보존해 반영하고, 정규화 후에도 기존 리소스가 없으면 신규 키를 추가하지 않고 제외한다. | P1-T3, P2-T1 |
JSR-006 |
확정 | CSV의 しいシリーズ JP 오탈자는 新しいシリーズ로 보정한다. |
해당 KR이 기존 한국어 리소스와 매칭될 때만 보정 JP를 반영한다. | P1-T3, P2-T1 |
JSR-007 |
확정 | 같은 KR 또는 같은 정규화 KR이 여러 I18n 항목에 중복되어 있고 기존 JP가 다르면 CSV JP를 우선한다. |
현재 스캔 기준 중복 KR의 기존 JP 상이 항목 12건은 CSV JP로 통일한다. | P1-T2, P2-T1 |
8.2 품질과 검증
| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
|---|---|---|---|---|
QA-001 |
확정 | 문자열 변경 후 두 앱 스킴 Debug 빌드를 실행한다. | SodaLive, SodaLive-dev Debug 빌드가 ** BUILD SUCCEEDED **로 끝난다. |
P2-GATE |
QA-002 |
확정 | 테스트 스킴 제약을 확인한다. | 테스트 액션 미구성 상태면 실패가 코드 실패가 아님을 Progress에 기록한다. | P2-GATE |
QA-003 |
확정 | 일본어 언어 선택 상태에서 대표 화면 수동 QA를 수행한다. | CSV 대표 문구, 개행, placeholder 표시를 스크린별로 확인하고 결과를 Progress에 남긴다. | P2-GATE |
QA-004 |
확정 | 민감 정보나 SDK 입력값을 번역 대상으로 오인하지 않는다. | 인증 토큰, API path, Bootpay/SDK 고정값은 변경하지 않는다. | P2-T1 |
9. UI/UX Expectations
- 기존 화면 레이아웃과 컴포넌트 구조를 유지한다.
- 일본어 번역이 길어져도 이번 작업에서는 레이아웃을 임의 조정하지 않는다. 잘림이 발견되면 후속 UI 이슈로 기록한다.
- 개행이 포함된 문구는 CSV 의도를 우선하고, 화면에서 부자연스러운 경우 제품·번역 담당자 확인 후 보정한다.
10. API 계약
해당 없음. 이 작업은 클라이언트 로컬 문자열 리소스 반영이다.
11. 보안과 데이터 취급
- 인증 헤더, 토큰 저장소,
UserDefaultsKey.token관련 로직은 변경하지 않는다. - 이메일 placeholder 문구는 예시 이메일을 문서나 테스트 fixture에 하드코딩하지 않는다.
- 구매/결제 SDK에 전달되는 고정 문자열은 사용자 노출 문구가 아닌 경우 번역하지 않는다.
12. 성능과 품질 요구사항
- 런타임 성능 요구사항은 변경하지 않는다.
- 신규 dependency를 추가하지 않는다.
- 문자열 선택 방식은 기존
I18n.pick구조를 유지한다. - 검증은 정적 매핑 점검, Xcode 빌드, 일본어 대표 화면 수동 QA로 수행한다.
13. 성공 기준
13.1 기능 수용 기준
- CSV 242행의 처리 상태가
기존 키 갱신,placeholder 정규화 후 기존 키 갱신,오탈자 보정 후 기존 키 갱신,기존 리소스 없음으로 제외중 하나로 분류된다. - 확정 항목의 일본어 문구가
I18n.swift에 반영된다. - placeholder와 개행 문구가 깨지지 않는다.
- CSV 셀 안의 실제 줄바꿈과 HTML br 표기는 문자열 그대로가 아니라 Swift 문자열
\n으로 반영된다. - 중복 KR 또는 중복 정규화 KR의 JP는 CSV JP 우선으로 정리된다.
- 기존 한국어 리소스가 없는 항목은 구현하지 않고 제외 사유가 문서화된다.
13.2 품질 수용 기준
SodaLiveDebug 빌드가 성공한다.SodaLive-devDebug 빌드가 성공한다.- 테스트 액션 실행 가능 여부와 결과가 기록된다.
- 일본어 언어 설정에서 대표 화면 수동 QA가 완료된다.
13.3 추적성 완료 기준
- 모든 확정 요구사항이
plan-task.md의 Goal과 연결된다. - 모든 제외 항목에 제외 근거와 영향 Goal이 있다.
- 구현 결과와 검증 기록은
plan-task.mdProgress에 누적된다.
14. Open Questions
| ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 기한/시점 | 영향 Goal |
|---|---|---|---|---|---|---|
OQ-001 |
확정 | CSV 물리 line 281~283의 JP 最近見たシリーズはありません。\nしいシリーズを見つけましょう！에서 しいシリーズ가 오탈자인지 확인이 필요했다. |
新しいシリーズを見つけましょう！로 보정한다. |
사용자 | 확정 완료 | P1-T3, P2-T1 |
OQ-002 |
확정 | {{장르}}, {{크리에이터이름}}, {email}, {요일}, n%, n위, 0:00 토큰을 Swift 함수 인자로 변환할지 결정이 필요했다. |
기존 한국어 리소스가 있는 항목만 함수 인자로 변환하고, 기존 한국어 리소스가 없는 항목은 반영하지 않는다. | 사용자 | 확정 완료 | P1-T3, P2-T1 |
OQ-003 |
확정 | CSV KR 원문 중 메세지, 메거진 같은 한국어 오탈자 후보를 보정할지 결정이 필요했다. |
한국어 리소스는 보정하지 않고 JP만 반영한다. | 사용자 | 확정 완료 | P1-T3, P2-T1 |
OQ-004 |
확정 | 기존 I18n.swift에 동일 KR literal이 없는 139개 항목을 신규 키로 추가할지 결정이 필요했다. |
기존 한국어 리소스가 없는 항목은 추가하지 않는다. | 사용자 | 확정 완료 | P1-T3, P2-T2 |
OQ-005 |
확정 | 신규 키 추가 시 CSV에 없는 en 값을 어떻게 채울지 결정이 필요했다. |
없는 리소스는 추가하지 않으므로 신규 en 작성도 하지 않는다. |
사용자 | 확정 완료 | P2-T2 |
OQ-006 |
확정 | {{키워드}}의 오디오처럼 {{...}} 형태로 들어간 CSV 문구를 기존 앱 리소스 매핑 후보로 볼지 결정이 필요했다. |
앱 내에서 변경 가능한 리소스이므로 Swift interpolation 문구와 정규화 매칭한다. | 사용자 | 확정 완료 | P1-T2, P2-T1 |
OQ-007 |
확정 | 중복 KR 항목의 기존 JP가 서로 다를 때 어떤 값을 우선할지 결정이 필요했다. | CSV JP를 우선 반영한다. | 사용자 | 확정 완료 | P1-T2, P2-T1 |
OQ-008 |
확정 | CSV에 HTML br 표기가 있을 때 앱 문자열에 그대로 반영할지 결정이 필요했다. | HTML br 표기는 literal이 아니라 Swift 문자열 줄바꿈 \n으로 변환한다. |
사용자 | 확정 완료 | P1-T1, P2-T1 |
OQ-009 |
확정 | CSV 셀 안의 실제 줄바꿈을 앱 문자열에 어떤 형태로 반영할지 결정이 필요했다. | CSV 실제 줄바꿈은 Swift 문자열 줄바꿈 escape \n으로 변환한다. |
사용자 | 확정 완료 | P1-T1, P2-T1 |
15. 요구사항 추적표
| 요구사항 범위 | API Contract | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
|---|---|---|---|---|---|
JSR-001 |
해당 없음 | 1 | P1-T1 |
CSV 파싱 명령 | CSV 행 수와 누락 확인 |
JSR-002 |
해당 없음 | 1, 2 | P1-T2, P2-T1 |
KR literal 매칭 스크립트, 빌드 | 일본어 대표 화면 확인 |
JSR-003~007 |
해당 없음 | 1, 2 | P1-T2, P1-T3, P2-T1, P2-T2 |
placeholder 정규화/개행/중복 JP 점검 스크립트 | 제외 목록과 보정 JP 리뷰 |
QA-001~004 |
해당 없음 | 2 | P2-GATE |
xcodebuild |
언어 설정 ja 수동 QA |
16. Decision Log
| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal |
|---|---|---|---|---|---|
2026-08-11 |
DEC-001 |
확정 | 이번 요청에서는 PRD와 plan-task.md만 생성하고 앱 코드는 수정하지 않는다. |
사용자 직접 지시 | 전체 |
2026-08-11 |
DEC-002 |
확정 | 일본어 문자열 반영의 기본 대상은 SodaLive/Sources/I18n/I18n.swift로 둔다. |
현재 코드의 I18n.pick(ko:en:ja:) 구조 확인 |
JSR-002, P2-T1 |
2026-08-11 |
DEC-003 |
폐기 | 신규 키 추가는 영어 기준과 호출부가 확인된 항목으로 제한한다. | 사용자 결정으로 기존 한국어 리소스가 없는 항목은 추가하지 않기로 변경 | JSR-003, OQ-004, OQ-005 |
2026-08-11 |
DEC-004 |
확정 | しいシリーズ는 新しいシリーズ로 보정한다. |
사용자 확인 | JSR-006, OQ-001, P2-T1 |
2026-08-11 |
DEC-005 |
확정 | placeholder 문구는 기존 한국어 리소스가 있는 항목만 Swift 함수 인자로 변환한다. | 사용자 결정 | JSR-005, OQ-002, P2-T1 |
2026-08-11 |
DEC-006 |
확정 | 한국어 리소스 원문은 보정하지 않고 JP만 반영한다. | 사용자 결정 | OQ-003, P2-T1 |
2026-08-11 |
DEC-007 |
확정 | 기존 한국어 리소스가 없는 CSV 항목은 신규 리소스로 추가하지 않는다. | 사용자 결정 | JSR-003, OQ-004, OQ-005, P2-T2 |
2026-08-11 |
DEC-008 |
확정 | {{...}}, {...}, n%, n위, 0:00 형태 placeholder는 Swift interpolation과 정규화해 매핑 후보를 판정한다. |
사용자 결정과 재스캔 결과 | JSR-002, JSR-005, OQ-006, P1-T2 |
2026-08-11 |
DEC-009 |
확정 | 같은 KR 또는 같은 정규화 KR의 기존 JP가 여러 값이면 CSV JP를 우선 반영한다. | 사용자 결정과 중복 JP 재스캔 결과 | JSR-007, OQ-007, P2-T1 |
2026-08-11 |
DEC-010 |
확정 | HTML br 표기는 앱 문자열에 그대로 반영하지 않고 줄바꿈 \n으로 변환한다. |
사용자 결정 | JSR-004, OQ-008, P2-T1 |
2026-08-11 |
DEC-011 |
확정 | CSV 셀 안의 실제 줄바꿈은 Swift 문자열 줄바꿈 escape \n으로 변환한다. |
사용자 결정 | JSR-004, OQ-009, P2-T1 |
17. 변경 관리
요구사항 변경 시 다음을 확인한다.
- Decision Log에 변경 이유와 날짜를 기록했다.
- 관련 요구사항 상태·본문·수용 기준을 갱신했다.
plan-task.md의 범위·Files·Interfaces·체크박스·완료 증거를 코드 변경 전에 갱신했다.- 기존 Progress와 검증 기록을 삭제하거나 덮어쓰지 않았다.