Appearance
프론티아 글로벌 — UI 현지화(i18n) PRD
앱·웹의 **UI 텍스트·날짜/통화/숫자 포맷·타이포그래피(줄바꿈·폰트; CJK·태국어)**를 유저 언어에 맞게 표시하는 토대. 한국어 하드코딩을 걷어내고 언어팩으로 외부화한다. 유저 언어·타임존 판정은 가입·온보딩 & 글로벌 토대 PRD, LLM 시스템 프롬프트의 언어 처리는 창작·발행 PRD 소관이다(본 PRD는 화면 텍스트만).
Status: draft Created: 2026-07-03 Last updated: 2026-07-06 대상 표면: 앱 / 웹 (공통 프론트 토대)
이 문서의 표기
- 마켓 코드: 콘텐츠 마켓 7개(NA·JP·KR·TW·LATAM·BR·ID). 마켓에 매핑되지 않은 국가는 NA로 매핑된다(별도 'ROW' 구분 없음). 본 PRD는 주로 언어를 다루며 마켓 정의는 가입·온보딩 & 글로벌 토대 PRD.
- UI 언어(유저가 설정에서 고르는 언어) — 정본 목록 8종: ko(한국어) · en(영어) · ja(일본어) · zh-Hant(번체 중국어) · es(스페인어) · pt(포르투갈어) · id(인니어) · th(태국어). UI 언어는 마켓과 무관 — 기기/브라우저로 디폴트를 잡고 유저가 바꾼다. UI 언어 수(8) ≥ 콘텐츠 마켓 수(7) — 태국어는 전용 콘텐츠 마켓이 없어도 UI 언어로 유지한다(태국 유저는 NA 마켓으로 매핑돼 영어 콘텐츠를 보되 화면은 자기 언어). 베트남어는 앱·캐릭터챗 수요가 약해 UI 언어에서도 제외(베트남 유저는 영어 UI + 영어 콘텐츠). (콘텐츠 언어는 에피소드별이며 창작·발행 소관.)
- i18n 용어: i18n=국제화(화면을 여러 언어로 낼 수 있게 만드는 토대) · 언어팩=언어별 UI 문자열 모음 · Intl/CLDR=날짜·통화·숫자를 언어 규칙으로 포맷하는 표준 · CJK=중국어·일본어·한국어 문자권.
- 되돌리기 비용 등급(R): R1=쉬움(문구·포맷 조정) · R2=중간(키 스킴·리소스 재작업).
- 표시 약속:
검토 필요=아직 정해지지 않음(§7) ·후속=출시 후 디테일 패스.
Reversal Risk Summary
| 레이어 | R등급 | 점검 초점 |
|---|---|---|
| 정책 / 규칙 | R1 | 언어 폴백=en 등 룰은 가벼움 |
| 데이터 / 백엔드 | R2 | 리소스 키 네임스페이스·번역 카탈로그 저장 위치. 키 스킴을 늦게 바꾸면 전 화면 재작업 |
| 유저 대면 화면 | R2 | i18n 프레임워크는 거의 전 클라 화면을 관통 → 늦게 도입할수록 신규 화면이 하드코딩으로 쌓임. 조기 픽스 필요 |
| 문구 / 시각 표현 | R1 | 개별 번역·타이포 파라미터는 출시 후 카탈로그 교체로 핫픽스 |
1. 목표 및 배경
1.1 목표
- 프론티아 글로벌 확장의 토대로, 앱·웹 모든 UI가 유저 언어로 표시되게 한다. 이 토대가 먼저 깔려야 다른 글로벌 클라이언트 작업이 한국어 하드코딩을 더 쌓지 않는다.
1.2 배경 (현황)
- 프론티아는 한국 전용으로 만들어져 UI 텍스트가 전부 한국어 하드코딩이고, 날짜·통화·숫자 포맷·폰트·줄바꿈이 한국어 기준이다. i18n 프레임워크가 통째로 없다.
- 이 토대가 없으면 비-한국어 유저는 화면을 읽을 수 없고, 신규 글로벌 화면마다 하드코딩이 계속 쌓인다.
1.3 접근
- 마켓별로 화면을 나누지 않고, 단일 코드베이스 + i18n 프레임워크 + 언어팩 8종(ko·en·ja·zh-Hant·es·pt·id·th) 으로 간다. 리소스 키로 전 화면 텍스트를 외부화하고, 리소스 누락 시 en으로 폴백한다.
- 언어별 포맷팅(날짜/통화/숫자)·타이포그래피(줄바꿈·워드랩·폰트 폴백·타이핑 연출; CJK·태국어)를 언어에 맞게 렌더한다.
- 1차 핵심 작업 = 하드코딩 한국어 문자열 전수 추출·번역(LLM 초벌 + 내부 리뷰).
2. 타깃 사용자
2.1 주요 사용자
- 직접: 8개 언어권 글로벌 유저 — 앱·웹 전 화면에서 자기 UI 언어로 화면을 본다.
- 간접: 다른 글로벌 클라 작업을 하는 개발자 — i18n 프레임워크로 신규 문자열을 외부화한다.
2.2 핵심 시나리오
- 영어 유저가 앱을 켜면 가입·온보딩·홈·플레이·상점·에러까지 모든 UI가 영어로 표시되고, 날짜·수량·가격이 영어권 포맷으로 보인다.
- 일본어 유저가 채팅하면 말풍선 안 텍스트가 일본어 줄바꿈 규칙으로 꺾이고, 타이핑 연출 속도·폰트가 일본어에 맞는다(말풍선을 몇 개로 쪼개는지는 언어 무관 공통).
- 번체 유저가 결제 화면에서 대만달러 통화·번체 숫자 포맷으로 가격을 보고, 해당 언어 리소스가 없는 일부 신규 화면은 영어로 폴백된다.
3. 핵심 기능 요구사항
3.1 클라이언트 (앱/웹)
앱·웹 공통. 프레임워크는 플랫폼별로 구현하되 리소스 키 네임스페이스·번역 카탈로그는 단일 원본으로 공유한다.
i18n 프레임워크 (앱·웹 공통)
- 동작: 모든 UI 텍스트를 하드코딩이 아닌 리소스 키로 표시하고, 유저 언어에 맞는 언어팩에서 문자열을 해석한다.
- 비즈니스 룰:
- 지원 언어팩 = 8종(ko 기존 + en·ja·zh-Hant·es·pt·id·th 신규).
- UI 언어 = 유저 언어(기기/브라우저로 디폴트, 설정에서 변경). 마켓과 무관 — 유저는 자기 마켓 콘텐츠를 보되 UI 언어는 따로 고른다.
- 폴백 = en: 언어팩에 키가 없으면 en으로, en에도 없으면 키가 노출되지 않게 안전 기본값으로.
- 1차 작업 = 하드코딩 한국어 문자열 전수 추출(앱+웹) → 외부화 → 번역(LLM 초벌 + 내부 리뷰).
- 가입 전(비로그인) 언어는 기기 지역·브라우저 언어 기반 잠정값 → 가입 후 유저 언어로 고정(판정·고정은 토대 PRD).
언어 설정 변경 (계정 설정) 🎨(신규)
- 동작: 유저가 계정 설정에서 자기 UI 언어를 직접 바꾼다. 진입점 = 계정 설정. 변경하면 전 화면에 즉시 반영된다.
- 비즈니스 룰: 지원 8종 중 선택. 기기/브라우저 디폴트를 유저가 이 화면에서 오버라이드한다. 변경 가능 규칙·저장은 토대 PRD 소관이고, 본 PRD는 선택 화면을 소유한다.
- 디자인 필요: 계정 설정 안 언어 선택 UI(신규 화면/항목)라 Figma 필요.
언어별 포맷팅 (날짜/통화/숫자)
- 동작: 날짜·시각·숫자·통화를 유저 언어 규칙으로 표시한다.
- 비즈니스 룰: Intl/CLDR 기반. 통화 표시는 유저 마켓의 스토어 통화(달러·엔·대만달러·페소·헤알·루피아·바트·동 등)로 갈리되 가격 값 자체는 결제·정산 PRD가 정한다(본 PRD는 포맷만). 타임존 의존 표시(상대시간 등)는 유저 타임존 값을 받아 포맷만 담당한다.
타이포그래피 (줄바꿈·워드랩 / 폰트 폴백 / 타이핑 연출)
- 동작: 언어별 스크립트에 맞게 텍스트의 줄바꿈·폰트·타이핑 연출을 렌더한다.
- 비즈니스 룰:
- 줄바꿈·워드랩: 텍스트가 어디서 꺾이는지가 언어별로 다르다 — CJK는 글자 단위 줄바꿈 + 금칙처리(문장부호가 줄머리/줄끝에 오지 않게), 한국어는 어절 유지(keep-all), 태국어는 단어 사이에 공백이 없다(공백은 문장·구 경계에만 있음). 그래서 공백 기준 줄바꿈은 문장이 통째로만 끊겨 긴 구절이 오버플로우한다 → 단어 경계를 인식하는 줄바꿈(플랫폼 텍스트 엔진의 태국어 로케일 / 사전·ICU 기반)이 필요하다. 채팅 말풍선 안 텍스트도 이 규칙을 그대로 받는다.
- 폰트 폴백: 기본 폰트가 커버하지 못하는 스크립트를 폴백으로 렌더한다 — 기본 폰트(예: Pretendard)엔 태국 문자가 없다. OS 기본 태국 폰트(iOS Thonburi·Android Noto Sans Thai·Windows Leelawadee)로 폴백돼 렌더 자체는 되지만 플랫폼마다 모양이 달라 브랜드 일관성이 깨지고 성조부호·모음이 위아래로 쌓여 line-height 여유도 필요하다 → 일관된 룩을 원하면 태국 웹폰트(예: Noto Sans Thai·Sarabun)를 번들하는 게 좋다. 일본어·번체도 커버리지가 부족하면 CJK 폰트 폴백이 필요하다. 즉 단일 폰트로 통일하는 게 아니라 스크립트별 폰트 폴백 체인을 둔다(미로드 시 시스템 폰트).
- 타이핑 연출: 플레이 화면 타이핑 연출 속도를 언어별로 파라미터화(선택, 후속 가능).
- 경계: 채팅 말풍선을 여러 개로 쪼개는 것(줄바꿈 기준 분할)은 언어와 무관한 공통 동작이라 i18n 별도 작업이 아니다. i18n이 다루는 건 그 말풍선 안 텍스트의 줄바꿈·폰트뿐이다.
마스터 라벨 · 에러 카탈로그
- 동작: 장르 마스터·UI 라벨, 에러·안내·입력 placeholder 문구를 언어 카탈로그에서 해석한다.
- 비즈니스 룰: 내부 키는 불변, 표시 라벨만 언어별로 매핑. 폴백 en.
3.2 어드민
- 본 PRD는 어드민 화면을 신규로 만들지 않는다. 번역 카탈로그 관리(키-언어별 문자열 입력·검수)는 1차엔 정적 리소스·스크립트로 갈음 가능(저장 위치는 §7).
3.3 백엔드 / 시스템
- 본 PRD는 UI 텍스트·포맷·타이포 리소스 토대만 제공한다. LLM 시스템 프롬프트의 언어 처리(언어 조건 블록)는 창작·발행 PRD 단독 소관이다(본 PRD 제외). 번역 방식(LLM 초벌+리뷰)은 원칙을 공유하나 자산 소유는 분리한다.
- 서버가 반환하는 유저 노출 문구의 현지화: 클라이언트 언어팩만으로는 서버가 보낸 문구가 현지화되지 않는다(에러 메시지·서버 조합 안내 등). 원칙:
- 기본 경로 — 서버는 완성 문구 대신 에러 코드/키를 반환하고, 클라이언트가 언어팩(에러 카탈로그, §3.1)으로 현지화한다.
- 불가피하게 서버가 완성 문구를 만들어 보내는 경우(서버 조합 메시지, 알림/푸시 payload 텍스트, 이메일 등)는 서버가 유저 언어 기준으로 현지화한다 — 유저 언어를 서버가 알거나 요청에 실어 전달(Accept-Language 등) + 서버 측 문자열 카탈로그가 필요하다.
- 푸시 알림 문구의 유저 언어 발송은 운영·어드민 PRD(전체·자동 푸시)가 소유한다. 본 PRD는 서버 문구 현지화의 원칙만 정하고, 발송 도구·타게팅은 운영·어드민 소관이다.
3.4 딥링크 / URL
- 신규 경로 없음. 표시 언어는 유저 언어(콘텐츠는 콘텐츠 언어) 기준이며, 크로스마켓 딥링크 접근 허용 여부는 탐색·플레이 소관.
3.5 Scope
포함 (In scope)
- 앱·웹 공통 i18n 프레임워크 + 단일 리소스 키 네임스페이스.
- 언어팩 8종(ko 기존 + en·ja·zh-Hant·es·pt·id·th), 하드코딩 한국어 전수 추출·외부화·번역.
- 언어별 포맷팅(날짜/시각/통화 표시/숫자).
- 타이포그래피: 언어별 줄바꿈·워드랩(태국어 단어경계 인식 포함)·스크립트별 폰트 폴백(태국어 웹폰트 권장 — OS 폴백 렌더는 됨·CJK 커버리지)·타이핑 연출. (말풍선 분할 자체는 공통이라 제외.)
- 언어 설정 변경 화면(계정 설정, 디자인 필요).
- 장르 등 마스터/UI 라벨·에러·placeholder 카탈로그 + 서버 반환 유저 문구 현지화 원칙(코드/키 반환, 서버 완성 문구는 서버 현지화).
제외 (Out of scope) — 인접 문서 경계
| 항목 | 소관 |
|---|---|
| 유저 언어·타임존 판정·고정 | 가입·온보딩 & 글로벌 토대 |
| LLM 시스템 프롬프트 언어 조건 블록, 콘텐츠(에피소드·캐릭터) 텍스트 번역 | 창작·발행 |
| 통화 가격 값 결정·결제 | 결제·정산 |
| 지역 로케일 세분(한 언어가 여러 지역·통화에 걸칠 때), 국가별 톤·안전 프롬프트 튜닝 | 2차 |
4. 에러 처리 및 예외 상황
| 상황 | 처리 방향 |
|---|---|
| 언어팩에 키 없음 | en 폴백 → 그래도 없으면 안전 기본 문자열(키 노출 금지) |
| 폰트 미로드 | 시스템 폰트 폴백 체인 |
| 번역 누락/오역 발견 | 카탈로그 핫픽스(앱 재배포 없이 교체 가능한 구조 지향) |
| 유저 언어 미확정(가입 전) | 기기 지역·브라우저 언어 잠정 → 폴백 en |
| CJK 줄바꿈 깨짐 | 언어별 규칙 미적용 시 기본 단어 단위 줄바꿈, QA 회귀 점검 |
5. 데이터 분석
- 신규 화면 이벤트를 많이 만들지 않는다. 기존 이벤트에 표시 언어 컨텍스트가 필요하면 속성으로 추가(
user_language·episode_language— 토대 PRD·탐색·플레이 명명 그대로 쓴다). - 언어팩 폴백 발생(번역 누락 탐지)을 모니터하는 이벤트를 둔다. 속성 규칙 원본은 토대 PRD.
6. Ubiquitous Language
마켓·언어 용어는 토대 PRD 용어표가 기준이다. 본 PRD 고유 용어(언어팩·폴백 언어=en)는 §표기·§3에서 정의했으므로 별도 표를 두지 않는다.
7. 검토 필요 (미결정 항목)
- [ ] 번역 카탈로그 저장 위치 — 정적 상수 vs DB(런타임 교체 가능). 핫픽스 용이성·어드민 관리 UI 필요 여부에 영향. (담당: 엔지니어)
- [ ] i18n 라이브러리·키 스킴을 앱·웹 단일 원본으로 공유하는 방식 — 키 네임스페이스 컨벤션. (담당: 엔지니어)
- [ ] 폰트 커버리지·라이선스·번들 크기 — 기본 폰트가 못 덮는 스크립트의 폴백 폰트(태국어 = OS 폴백 렌더는 되나 일관성 위해 웹폰트 번들 권장, CJK 커버리지), 번들 vs 시스템 폰트 의존. (담당: 엔지니어/디자이너)
외부 grounding 필요 (구현 시 코드에서 확인)
- 앱·웹의 기존 i18n 흔적, 하드코딩 한국어 문자열 분포·규모, 포맷 호출 지점, 폰트/타이포 설정 위치 스캔(추출 작업 사이징).
부록: 메타 정보
Required artifacts
- Spec — 프론트 토대 메모(i18n 적용·포맷·라이브러리)로 갈음.
- Design — ①언어 설정 변경 화면(계정 설정 내 언어 선택 UI) 신규 → Figma 필요. ②언어별 폰트/타이포 토큰·줄바꿈 가이드(태국어 폰트·무공백 줄바꿈 포함). 그 외 화면 레이아웃은 기존 재사용.
- Migration plan — 조건부(번역 카탈로그를 DB로 둘 경우만). 별도 파일 아님.
Size & Risks
- Size: L / Confidence: medium — 프레임워크 자체는 표준이나 전 클라 화면 하드코딩 전수 추출이 앱·웹 양쪽이라 범위가 큼. 언어별 타이포(줄바꿈·폰트; CJK·태국어)·플레이 연출까지 포함.
- 위험: ①늦게 도입하면 신규 글로벌 화면이 하드코딩 누적(대응: 클라 글로벌 작업의 선행 토대로 우선) ②번역 품질(대응: 내부 리뷰 게이트 + 카탈로그 핫픽스) ③CJK 타이포 회귀(대응: 언어별 파라미터 분리, 한국어 회귀 QA).
- 의존: 가입·온보딩 & 글로벌 토대(유저 언어·타임존 값 공급). 창작·발행(프롬프트 프레임 소유). 결제·정산(통화 가격 값).
References
- 위키 근거(As-is): i18n/다국어/로케일 코드 검색 0건 — 신규 토대. frontia-wiki foundation/ubiquitous-language.
- 결정 로그 원문: CLAUDE.md §8.