i18n

11개 언어 번역 파일(`ko.i18n.json` 등)에 문구를 추가·정리하고 복수형·자리표시자를 표준 방식으로 맞춘 뒤 `translations.g.dart` 를 생성하고 빠진 번역이 없는지 점검합니다.

항목	내용
실행 명령	`/cc-i18n:i18n`
분류	개발
난이도	●●○ 보통
MCP 서버	`serena`, `context7`

한마디로#

화면에 보이는 모든 문구(버튼, 안내 메시지 등)를 여러 나라 언어로 번역해 관리해 주는 도구입니다. 한국어로 적은 문장에 "영어로는 이렇게"라고 짝을 지어주면, 앱이 사용자의 언어에 맞춰 알아서 보여줍니다. 단어장에 새 단어와 뜻을 추가하는 것과 비슷해요.

누가·언제 쓰나요#

화면에 새로운 문구를 추가하면서 한국어·영어 번역을 함께 등록하고 싶을 때
여러 나라 언어로 보여주는 다국어 텍스트를 관리할 때
코드에서 context.i10n.* 같은 번역 문구 호출 방식을 다룰 때

무엇을 해주나요#

번역 문구를 정리해 두는 파일(shared/i10n/lib/src/json/ko.i18n.json, en.i18n.json 등 한국어·영어를 포함한 11개 언어 파일)에 새 문구를 추가·정리해 줍니다.
"1개", "2개"처럼 개수에 따라 말이 달라지는 복수형 처리나 {name}님 같은 자리표시자(이름·숫자 등 바뀌는 값) 처리를 표준 방식으로 맞춰 줍니다.
코드로 변환된 결과물(translations.g.dart)을 만들고, 빠진 번역이 없는지 점검해 줍니다.

어떻게 쓰나요#

# 새 번역 추가 (한국어·영어 함께)
/i18n add home.new_feature --ko "새로운 기능" --en "New Feature"

# 개수에 따라 말이 달라지는 복수형 번역 추가
/i18n add cart.item_count --ko "상품" --en "item" --plural

# 빠진 번역이 없는지 점검
/i18n check

add(추가)·update(수정)·check(점검) 중 할 일을 고르고, home.welcome처럼 문구의 위치(키 경로)를 적습니다.
--ko에는 한국어, --en에는 영어 문장을 넣고, 개수에 따라 표현이 달라지면 --plural을 덧붙입니다.

안에서 무슨 일이 벌어지나요#

문구 등록 — 한국어를 기준으로 번역 파일에 새 문구를 추가하고, 영어 등 다른 언어 짝을 맞춰 정리합니다.
자동 번역·코드 생성 — 영어 자동 번역(GPT)을 돌리거나, 번역 파일을 앱이 쓸 수 있는 코드로 변환합니다(melos run generate:locale).
점검 — 빠진 번역이 없는지 확인하고(dart run slang analyze), 하드코딩된(번역 키를 거치지 않은) 문구가 없도록 규칙을 지킵니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Triggers#

When adding new translation keys
When managing multilingual text
When using context.i10n.* patterns

Context Trigger Pattern#

/i18n {action} {key_path} [--options]

Parameters#

Parameter	Required	Description	Example
`action`	✅	Action to perform	`add`, `update`, `check`
`key_path`	✅	Translation key path	`home.welcome`, `auth.login`
`--ko`	❌	Korean text	`"환영합니다"`
`--en`	❌	English text	`"Welcome"`
`--plural`	❌	Pluralization handling	`true`

File Structure#

shared/i10n/lib/src/
├── json/
│   ├── ko.i18n.json          # Base (Korean)
│   ├── en.i18n.json          # English
│   └── ... (ja, zh-Hans, de, fr, es, it, pt, ru, ar)
└── translations/              # Generated code
    ├── translations.g.dart    # AppLocale, LocaleSettings
    ├── translations_ko.g.dart # Base locale
    └── ...                    # One file per locale (en, ja, ...)

Translation File Format#

Basic Structure#

// shared/i10n/lib/src/json/ko.i18n.json
{
  "common": {
    "app_name": "Unibook",
    "ok": "확인",
    "cancel": "취소",
    "save": "저장",
    "loading": "로딩 중...",
    "error": "오류가 발생했습니다"
  },
  "auth": {
    "login": "로그인",
    "logout": "로그아웃",
    "sign_up": "회원가입",
    "email": "이메일",
    "password": "비밀번호"
  }
}

Placeholders#

{
  "user": {
    "greeting": "{name}님, 안녕하세요!",
    "points": "{count} 포인트 보유",
    "join_date": "{date}에 가입"
  }
}

Pluralization#

{
  "items": {
    "count(param=n)": {
      "zero": "항목 없음",
      "one": "항목 1개",
      "other": "항목 {n}개"
    }
  },
  "messages": {
    "unread(param=count)": {
      "zero": "읽지 않은 메시지 없음",
      "one": "읽지 않은 메시지 1개",
      "other": "읽지 않은 메시지 {count}개"
    }
  }
}

Context-Based#

{
  "pet": {
    "type(context=PetType)": {
      "dog": "강아지",
      "cat": "고양이",
      "bird": "새"
    }
  }
}

Code Usage#

Basic Usage#

// Using BuildContext extension (provided by package:core)
Text(context.i10n.common.app_name)
Text(context.i10n.auth.login)
Text(context.i10n.home.title)

Placeholders#

Text(context.i10n.user.greeting(name: user.name))
Text(context.i10n.user.points(count: user.points.toString()))

Pluralization#

Text(context.i10n.items.count(n: itemCount))
Text(context.i10n.messages.unread(count: unreadCount))

Commands#

# Generate translation code
melos run generate:locale

# GPT auto-translation (English)
melos run translate:slang

# Check for missing translations
dart run slang analyze

Core Rules#

Naming Conventions#

Use nested structures: user.profile.title
Use snake_case (key_case: snake)
Use meaningful key names

Translation Rules#

All UI text must use translation keys
Hard-coded strings are prohibited
Pluralization must always be handled

Code Generation#

Run melos run generate:locale after modifying translation files
Do not manually edit generated code

MCP Integration#

Step	MCP Server	Purpose
Pattern analysis	Context7	slang documentation
Code search	Serena	Reference existing translation patterns

Examples#

Add New Translation#

/i18n add home.new_feature --ko "새로운 기능" --en "New Feature"

Add Plural Translation#

/i18n add cart.item_count --ko "상품" --en "item" --plural

Check Missing Translations#

/i18n check

References#

Detailed implementation: .claude/agents/i18n.md
Translation files: shared/i10n/lib/src/json/