i18n Reference

Detailed API and syntax reference for slang-based internationalization.

i18n Reference Guide#

Detailed API and syntax reference for slang-based internationalization.

YAML Syntax Reference#

Basic Strings#

common:
  appName: 펫메디
  ok: 확인
  cancel: 취소
  save: 저장
  loading: 로딩 중...

Nested Structure#

auth:
  login:
    title: 로그인
    button: 로그인하기
    error: 로그인에 실패했습니다
  signup:
    title: 회원가입
    button: 가입하기

Parameters (Placeholders)#

user:
  greeting:  ' $name님, 안녕하세요! ' 
   points:  ' $count 포인트 보유 ' 
   joinDate:  ' $date에 가입 '

Dart Usage:

context.t.user.greeting(name: 'John')
context.t.user.points(count: '100')

Pluralization#

items:
  count(param=n):
    zero: 항목 없음
    one: 항목 1개
    other: 항목 $n개

cart:
  itemCount(param=count):
    zero: 장바구니가 비어있습니다
    one: 장바구니에 상품 1개
    other: 장바구니에 상품 $count개

Dart Usage:

context.t.items.count(n: 0)     // "항목 없음"
context.t.items.count(n: 1)     // "항목 1개"
context.t.items.count(n: 5)     // "항목 5개"

Context-Based#

pet:
  type(context=PetType):
    dog: 강아지
    cat: 고양이
    bird: 새
    other: 반려동물

gender:
  pronoun(context=Gender):
    male: 그
    female: 그녀
    other: 그들

Dart Usage:

context.t.pet.type(context: PetType.dog)  // "강아지"

Rich Text#

terms:
  agreement:  ' 이용약관에 동의합니다.  < link > 자세히 보기 < /link > '

Dart Usage:

context.t.terms.agreement(
  link: (text) => TextSpan(
    text: text,
    style: TextStyle(color: Colors.blue),
    recognizer: TapGestureRecognizer()..onTap = () => openTerms(),
  ),
)

File Structure Reference#

Directory Layout#

shared/
├── i10n/                           # App translations
│   └── lib/
│       ├── translations/
│       │   ├── strings.i18n.yaml   # Base (Korean)
│       │   └── strings_en.i18n.yaml # English
│       └── src/
│           └── translations/
│               └── translations.g.dart
│
└── i10n_web/                       # Web translations (separate)
    └── lib/
        ├── translations/
        │   ├── strings.i18n.yaml
        │   └── strings_en.i18n.yaml
        └── src/
            └── translations/
                └── translations.g.dart

slang.yaml Configuration#

base_locale: ko
fallback_strategy: base_locale
input_directory: lib/translations
input_file_pattern: .i18n.yaml
output_directory: lib/src/translations
output_file_name: translations.g.dart
output_format: single_file
key_case: camel
key_map_case: camel
param_case: camel
string_interpolation: dart
flat_map: false
timestamp: true
statistics: true

Code Usage Reference#

Basic Access#

import 'package:i10n/i10n.dart';

// BuildContext extension
Text(context.t.common.appName)

// Direct access (without context)
final appName = AppLocale.ko.translations.common.appName;

App Configuration#

MaterialApp(
  locale: TranslationProvider.of(context).flutterLocale,
  supportedLocales: AppLocaleUtils.supportedLocales,
  localizationsDelegates: GlobalMaterialLocalizations.delegates,
)

Locale Switching#

// Change locale
LocaleSettings.setLocale(AppLocale.en);

// Check current locale
final currentLocale = LocaleSettings.currentLocale;

// Use system locale
LocaleSettings.useDeviceLocale();

Web Translations (Separate)#

import 'package:i10n_web/i10n_web.dart';

// Web-specific translations
Text(context.wt.common.title)

Command Reference#

Code Generation#

# Generate translation code
melos run generate:locale

# Force regeneration
cd shared/i10n  & &   dart run slang

GPT Auto-Translation#

# English auto-translation (API key required)
melos run generate:locale:gpt

# Direct execution
cd shared/i10n  & &   dart run slang:gpt

Analysis#

# Check for missing translations
dart run slang analyze

# Output statistics
dart run slang analyze --stats

Troubleshooting#

Translations Not Applied#

Symptom	Cause	Solution
Key not found error	Code not generated	Run `melos run generate:locale`
English not displayed	English file missing	Check `strings_en.i18n.yaml`
Pluralization not working	Syntax error	Verify `param=n` format

Code Generation Errors#

Symptom	Cause	Solution
YAML parsing error	Indentation error	Standardize to 2 spaces
Duplicate key error	Same key exists	Rename the key
Parameter error	Missing $	Use `$name` format

GPT Translation Errors#

Symptom	Cause	Solution
API error	Missing key	Set OPENAI_API_KEY environment variable
Low translation quality	Lack of context	Provide hints via comments

Best Practices#

Key Naming#

# ✅ Good example
user:
  profile:
    editButton: 프로필 수정
    saveButton: 저장

# ❌ Bad example
editProfileBtn: 프로필 수정  # Not using nested structure
user_profile_save: 저장       # Using snake_case

Pluralization Handling#

# ✅ Handle all cases
notifications:
  count(param=n):
    zero: 알림 없음
    one: 알림 1개
    other: 알림 $n개

# ❌ Incomplete handling
notifications:
  count:  ' 알림 $n개 '    # 0 and 1 cases not handled

Parameter Documentation#

# ✅ Document parameters with comments
user:
  # name: User ' s name
  greeting:  ' $name님, 안녕하세요! ' 

   # count: Number of points held
  points:  ' $count 포인트 '