slang-i18n Reference

Detailed API and syntax reference for slang-based internationalization.

i18n Reference Guide#

Detailed API and syntax reference for slang-based internationalization.

JSON Syntax Reference#

Translation files use the .i18n.json format with snake_case keys and {param} (braces) string interpolation. See slang.yaml below.

Basic Strings#

{
   " common " : {
     " app_name " :  " Unibook " ,
     " ok " :  " 확인 " ,
     " cancel " :  " 취소 " ,
     " save " :  " 저장 " ,
     " loading " :  " 로딩 중... " 
   }
}

Nested Structure#

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

Parameters (Placeholders)#

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

Dart Usage:

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

Pluralization#

{
   " items " : {
     " count(param=n) " : {
       " zero " :  " 항목 없음 " ,
       " one " :  " 항목 1개 " ,
       " other " :  " 항목 {n}개 " 
     }
  },
   " cart " : {
     " item_count(param=count) " : {
       " zero " :  " 장바구니가 비어있습니다 " ,
       " one " :  " 장바구니에 상품 1개 " ,
       " other " :  " 장바구니에 상품 {count}개 " 
     }
  }
}

Dart Usage:

context.i10n.items.count(n: 0)     // "항목 없음"
context.i10n.items.count(n: 1)     // "항목 1개"
context.i10n.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.i10n.pet.type(context: PetType.dog)  // "강아지"

Rich Text#

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

Dart Usage:

context.i10n.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/
        └── src/
            ├── json/
            │   ├── ko.i18n.json       # Base (Korean)
            │   ├── en.i18n.json       # English
            │   ├── ja.i18n.json       # Japanese
            │   ├── zh-Hans.i18n.json  # Simplified Chinese
            │   ├── de.i18n.json       # German
            │   ├── fr.i18n.json       # French
            │   ├── es.i18n.json       # Spanish
            │   ├── it.i18n.json       # Italian
            │   ├── pt.i18n.json       # Portuguese
            │   ├── ru.i18n.json       # Russian
            │   └── ar.i18n.json       # Arabic
            └── translations/
                └── translations.g.dart

slang.yaml Configuration#

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

Code Usage Reference#

Basic Access#

// context.i10n extension is provided by package:core (not package:i10n)
import 'package:core/core.dart';

// BuildContext extension
Text(context.i10n.common.app_name)

// Direct access (without context) — translate_var is `translations`
final appName = AppLocale.ko.translations.common.app_name;

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();

Command Reference#

Code Generation#

# Generate translation code (melos → dart run slang)
melos run generate:locale

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

GPT Auto-Translation#

# Translate base locale → all locales
melos run translate:slang

# Variants
melos run translate:en           # English only
melos run translate:incremental  # only missing keys
melos run translate:full         # full re-translation
melos run translate:all          # all locales
melos run translate:fix          # fix/repair pass

# 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 `en.i18n.json`
Pluralization not working	Syntax error	Verify `param=n` format

Code Generation Errors#

Symptom	Cause	Solution
JSON parsing error	Invalid JSON	Validate trailing commas / quotes
Duplicate key error	Same key exists	Rename the key
Parameter error	Wrong delimiters	Use `{name}` (braces) 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: nested structure + snake_case
{
   " user " : {
     " profile " : {
       " edit_button " :  " 프로필 수정 " ,
       " save_button " :  " 저장 " 
     }
  }
}

// ❌ Bad example
{
   " editProfileBtn " :  " 프로필 수정 " ,  // camelCase, not nested
   " user_profile_save " :  " 저장 "          // flat instead of nested
}

Pluralization Handling#

// ✅ Handle all cases
{
   " notifications " : {
     " count(param=n) " : {
       " zero " :  " 알림 없음 " ,
       " one " :  " 알림 1개 " ,
       " other " :  " 알림 {n}개 " 
     }
  }
}

// ❌ Incomplete handling
{
   " notifications " : {
     " count " :  " 알림 {n}개 " 
   }
}

Parameter Notes#

JSON files do not support comments, so document parameters in the PR / key design notes. Parameter names must be identical across all locale files.

{
   " user " : {
     " greeting " :  " {name}님, 안녕하세요! " ,
     " points " :  " {count} 포인트 " 
   }
}