| 항목 | 내용 |
|---|
| 기능 ID | FEAT-GLOBAL |
| 연결 시스템 | 마스터 시스템⑫ 글로벌 · 전 시스템에 적용되는 횡단 관심사(i18n) |
| 한 줄 정의 | 다국어·현지 통화/긴급번호/문화에 맞춰 실벗을 다른 나라에 확장한다 |
| 관련 액터 | PWA실벗서버아리 |
설계 철학 — 글로벌은 "번역"이 아니라 "현지화(Localization)"입니다. 언어·긴급번호·통화·문화·아리의 말투까지 그 나라 어르신에게 맞춥니다. 모든 기능(d01~d11)에 적용되는 횡단 설계.
▍설계 7계층 체크리스트
| 계층 | 이 문서의 섹션 |
|---|
| ① UI | 언어·지역 설정 SCR-GLB-01 + 전 화면 i18n 적용 |
| ② Flow | 로케일 결정 → 리소스 로드 → 현지화 적용 |
| ③ Data | locales / translations / region_settings |
| ④ API | 로케일·번역 리소스·지역설정 엔드포인트 |
| ⑤ Seq | 로케일 협상 → 현지화 적용 시퀀스 |
| ⑥ Comp | i18n 미들웨어·번역 리소스 구조 |
| ⑦ Test | 검수 체크리스트 |
② Flow · 로케일 결정·적용
앱 실행→
로케일 협상(설정>기기>기본)→
번역 리소스 로드→
지역 설정 적용→
현지화 렌더
우선순위: 사용자 명시 설정 > 기기 언어 > 기본(ko). 번역 누락 키는 기본 언어로 폴백(빈 화면 금지).
③ Data · DB 스키마
MariaDB · UTF8MB4 · InnoDB
CREATE TABLE locales (
code VARCHAR(10) PRIMARY KEY, -- 'ko','en','ja'
name VARCHAR(40),
is_active TINYINT DEFAULT 1
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE translations (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
locale VARCHAR(10) NOT NULL,
t_key VARCHAR(120) NOT NULL, -- 'home.greeting'
t_value TEXT,
UNIQUE KEY uq_t (locale, t_key),
FOREIGN KEY (locale) REFERENCES locales(code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE region_settings (
region VARCHAR(10) PRIMARY KEY, -- 'KR','US','JP'
emergency_no VARCHAR(10), -- '119','911'
currency VARCHAR(10), -- 'KRW','USD'
date_fmt VARCHAR(20)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
설계 포인트 — 긴급번호는 region_settings에서 가져와 d02 SOS의 119 호출을 자동 치환. 글로벌 확장 시 생명 안전 로직을 다시 짜지 않는다.
④ API · 엔드포인트 명세
| M | 경로 | 설명 |
|---|
| GET | /i18n/{locale} | 번역 리소스 번들(캐시 가능) |
| PUT | /me/locale | 사용자 언어·지역 설정 |
| GET | /i18n/region/{region} | 지역 설정(긴급번호·통화) |
응답의 {success,data,meta} 구조 안에서 어르신용 message는 항상 사용자 로케일로 내려간다.
⑤ Seq · 로케일 협상·적용
PWA
앱 실행 → 저장된 로케일 또는 기기 언어 판정 → GET /i18n/{locale}
실벗
번역 번들 반환(ETag 캐시) + region_settings 동봉
PWA
i18n 적용 + 긴급번호·통화·날짜 포맷 치환
아리
로케일을 프롬프트에 주입 → 현지 언어·말투로 응답(d01)
폴백 — 번역 키 누락 시 기본 언어(ko)로 표시. 절대 빈 문자열/키 노출 금지.
⑥ Comp · 컴포넌트 / 모듈 구조
프론트엔드 (PWA)
core/i18n/
├─ i18n.js # t(key) 번역 함수·폴백
├─ LocaleProvider.js # 전역 로케일 상태
├─ formatters.js # 통화·날짜·숫자
└─ LocaleSettings.js # 언어·지역 설정 화면
백엔드 (PHP)
app/
├─ Controllers/I18nController.php
├─ Middleware/LocaleMiddleware.php # 요청별 로케일 결정
└─ Services/ TranslationService.php # 번들·폴백
| 모듈 | 책임 |
|---|
LocaleMiddleware | 모든 요청에서 로케일 결정(헤더·사용자설정). 응답 message를 해당 언어로. |
i18n.js (t) | 전 화면 공통 번역 함수. 누락 키는 기본 언어 폴백. |
⑦ Test · 검수 체크리스트
| ID | 시나리오 | 기대 결과 |
|---|
| T-01 | 언어를 English로 변경 | 전 화면 문구·아리 응답 영어로 전환 |
| T-02 | 지역을 US로 설정 | 긴급번호 911·통화 USD·날짜 포맷 적용 |
| T-03 | US 지역에서 SOS 발동(d02) | 119 대신 911로 자동 호출 |
| T-04 | 번역 키 누락 | 기본 언어(ko)로 폴백, 빈 화면/키 노출 0 |
| T-05 | 오프라인 재실행 | 캐시된 번역 번들로 정상 표시 |
완료 판정 — T-01~T-05 통과 시 FEAT-GLOBAL 완료. T-03(긴급번호 치환)·T-04(폴백)는 글로벌 확장의 생명·안정성 핵심.
기능설계 ⑫ 완성 — 12대 시스템 전체 설계 완료! 글로벌은 d01~d11 모든 기능에 적용되는 횡단 설계입니다. 이로써 실벗 개발 설계서의 12대 시스템이 7계층(UI→Flow→DB→API→Seq→Comp→Test)으로 모두 완성되었습니다.