i18n

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

/i18n — 다국어 번역 도우미#

항목	내용
실행 명령	`/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/
    └── translations.g.dart    # Generated code

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/