Localization

한국어·영어·일본어 글로서리, 문자열 아키텍처, i18n 제약사항.

Source of truth: packages/locales/src/{ko,en,ja}/common.json

0. 정책 개요

영어 전용 (English-Across-Locales) 라벨

일부 UI 라벨은 모든 로케일에서 영어로 유지됩니다 — 의도적 global-premium 일관성.

• Login 헤드라인 ("Get Started with Tiro", "Perfectly crafted meeting notes")
• AI 채팅 인사말 ("Hi [name], Nice to see you again")
• AI 채팅 placeholder ("Ask anything to tiro")
• SSO 버튼 라벨 ("Continue with Google" 등)

그 외 in-app 기능 라벨 (탭, 버튼, 섹션 헤더)은 완전 로컬라이즈됩니다.

Brand Display Fonts per Locale

한국어 UI 헤드라인은 Pretendard JP 기본 — 한글 세리프는 Averia의 따뜻함 부족.

1. Glossary — Product Nouns

1.1 Product identity

"Tiro" 단독 사용 금지 — KO에서는 반드시 "티로 Tiro" 병기.

1.2 Core objects

1.3 People / identity

1.4 Primary actions

1.5 Navigation / tabs

1.6 Recording tabs (recording start panel)

1.7 Note view tabs

1.8 Language pair labels

1.9 Status / states

1.10 Billing / subscription

1.11 AI / intelligent features

AI 관련 라벨은 English-Across-Locales — premium 일관성 + 브랜드 모멘트.

1.12 Empty / error states

1.13 Onboarding / first-use

1.14 Time / frequency

날짜·시간 포맷은 Intl.DateTimeFormat + locale. 수동 포맷 금지.

1.15 Marketing / taglines

EN

• Perfectly Crafted Meeting Notes
• The Most Accurate AI Meeting Assistant
• No more note-taking. Just focus on your conversation.
• Meet Tiro. Your meetings, perfectly remembered.

KO

• 티로 Tiro — 가장 정확한 AI 미팅노트
• 대화에만 집중할 수 있게, 가장 정확한 AI 회의록
• 실시간 요약·다국어 동시 번역으로 자신있게 대화하고 원하는 양식의 문서를 3초 만에 완성하여 공유해보세요

JP

• Tiro：AI議事録・文字起こし
• 録音から要約まで、すべて自動。
• 完璧な議事録を、自動で。

2. i18n Constraints

2.1 문장 구조

• 문장 파편 concatenation 금지 — 로케일별 완전 문장
  • ❌ "Your " + count + " notes"
  • ✅ t('noteCount', { count }) → "노트 3개" / "3 notes" / "ノート 3件"
• EN → KO/JA는 30–40% 길이 확장 허용 — fixed px width 금지
• 한 문장 내 언어 혼용 금지 — "Tiro를 download하세요" 같은 표현 금지

2.2 존댓말 / 문체

• KO 시스템 카피: 합쇼체 (formal) 기본
• KO 반말: 팀 내부 툴, 실험적 CS 봇 문구만
• EN: sentence case 기본, Title Case는 브랜드 모멘트 (히어로, SSO 버튼)만
• JP: 문장체 (です/ます) 기본. 마케팅 헤드라인은 句点 "。" 사용 허용

2.3 숫자 / 통화 / 날짜

• 숫자 표시: tabular-nums CSS 적용 (통화, 시간, 카운터)
• 날짜/시간: Intl.DateTimeFormat(locale) 사용
• 통화: Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' })
• JP 통화 포맷: ¥1,200 (한자 금액 "千二百円" 쓰지 않음)

2.4 Right-to-left (RTL)

현재 미지원. v0.3 기준 RTL 레이아웃 작업 대상 아님. 필요 시 별도 결정.

3. String Architecture

3.1 저장 위치

컴포넌트는 브랜드 카피 하드코딩 절대 금지 — title, description, label을 props로 받음.

3.2 Key naming convention

common.json key 패턴: <surface>.<component>.<role>

예:

{
  "recording.tabs.offline": "녹음하기",
  "recording.tabs.live": "실시간 기록",
  "recording.controls.start": "기록 시작",
  "paywall.plans.pro.name": "프로",
  "empty.notes.title": "아직 노트가 없어요",
  "empty.notes.description": "첫 회의를 녹음하면 여기에 나타납니다",
  "empty.notes.cta": "녹음 시작"
}

금지 패턴:

• ❌ Surface 없는 flat key (start, save) — 컨텍스트 상실
• ❌ 문장 파편으로 분해된 key (paywall.part1, paywall.part2)
• ❌ HTML/마크다운이 포함된 value

3.3 Pluralization

ICU message format 또는 i18next plural 사용. 직접 if (count === 1) 분기 금지.

// ko
"noteCount": "노트 {count}개"
// en
"noteCount_one": "{count} note",
"noteCount_other": "{count} notes"
// ja
"noteCount": "ノート {count}件"

KO/JA는 단/복수 구분 없음 → single form.

4. Extraction / Sync Tooling

4.1 추출 스크립트 템플릿

common.json 스냅샷을 DS 문서 glossary 포맷으로 변환:

// scripts/extract-glossary.ts
import ko from '@/locales/ko/common.json'
import en from '@/locales/en/common.json'
import ja from '@/locales/ja/common.json'

const rows: string[] = []
for (const key of Object.keys(ko)) {
  const koVal = ko[key] ?? '⚠️ missing'
  const enVal = en[key] ?? '⚠️ missing'
  const jaVal = ja[key] ?? '⚠️ missing'
  rows.push(`| ${key} | ${koVal} | ${enVal} | ${jaVal} |`)
}
console.log(rows.join('\n'))

출력 → DS 문서 glossary 섹션에 붙여넣기. 누락 로케일이 ⚠️ missing 표시되어 발견 쉬움.

4.2 누락 감지 CI

Pre-commit 또는 CI 스텝:

# 모든 로케일이 동일한 key 집합을 가지는지 검증
diff <(jq -r 'keys[]' ko/common.json | sort) \
     <(jq -r 'keys[]' en/common.json | sort)

누락 key 발견 시 CI fail.

5. Do / Don't

• Do: 모든 product noun을 KO/EN/JA에 동시 확보 (신규 feature PR 머지 전)
• Do: 로케일별 native-authored 카피 (writing.md 참고) — 기계적 번역 금지
• Do: 시간·숫자·날짜는 Intl API로 로케일 자동 포맷
• Do: Key를 <surface>.<component>.<role> 패턴으로
• Don't: 문장 파편 concatenation ("Your " + count + " notes") 금지
• Don't: fixed px width로 텍스트 길이 제한 금지
• Don't: 영어 원문을 기계적으로 KO/JA 번역 (시장별 native tone 유지)
• Don't: Plural 처리를 if/else로 직접 분기 금지
• Don't: 한 문장 내 언어 혼용 금지