i18n Conventions

This project uses the **slang** package for internationalization (i18n).

This project uses the slang package for internationalization (i18n).

Translation Access API#

Project Standard: `context.i10n`#

// ✅ CORRECT: Import from package:core (standard)
import 'package:core/core.dart';  // Includes BuildContextExt

final translations = context.i10n.console.sample_book;
Text(context.i10n.common.save)

// ❌ WRONG: Do not import directly from package:i10n
import 'package:i10n/i10n.dart';  // Causes extension conflict!

// ❌ WRONG: Do not use context.translations
final translations = context.translations.console.sample_book;  // Do not use

Statistics: context.i10n 389 occurrences vs context.translations 1 occurrence (legacy)

⚠️ Extension Conflict Warning (ambiguous_extension_member_access)#

The context.i10n extension is provided only from package:core.

Package	Extension	Usage
`package:core/core.dart`	`BuildContextExt.i10n`	✅ Standard
`package:i10n/i10n.dart`	-	❌ No extension

Import Rules:

// ✅ CORRECT: Import only core
import 'package:core/core.dart';

// ✅ CORRECT: When only the extension is needed
import 'package:core/core.dart' show BuildContextExt;

// ⚠️ Note: i10n package does not provide an extension
// It only exports slang translation files and LocalizationsDelegate
import 'package:i10n/i10n.dart';

Note: The duplicate extension from package:i10n was removed in PR #2079. Previously, both packages provided context.i10n, causing ambiguous_extension_member_access errors.

Available APIs#

API	Status	Description
`context.i10n`	✅ Standard	Used across the entire project
`context.translations`	❌ Do not use	Exists only in legacy code

JSON Key Naming Conventions#

Use snake_case (Required)#

// ✅ CORRECT: Use snake_case
{
   " console " : {
     " sample_book " : {
       " user_status " : {
         " active " :  " 활성 " ,
         " inactive " :  " 비활성 " 
       }
    }
  }
}

// ❌ WRONG: Do not use camelCase
{
   " console " : {
     " sampleBook " : {  // Incorrect!
       " userStatus " : {  // Incorrect!
         " active " :  " 활성 " 
       }
    }
  }
}

Key Naming Patterns#

Pattern	Example	Description
Feature name	`sample_book`, `sales_analysis`	Feature module name
Action	`create`, `update`, `delete`	CRUD actions
State	`loading`, `error`, `success`	State messages
Error	`invalid_date_range`, `not_found`	Error messages

JSON File Structure#

File Locations#

shared/i10n/lib/src/json/
├── ko.i18n.json      # Korean (base)
├── 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

Hierarchy#

{
   " common " : {
     " save " :  " 저장 " ,
     " cancel " :  " 취소 " ,
     " confirm " :  " 확인 " 
   },
   " console " : {
     " sample_book " : { ... },
     " sales_analysis " : {
       " period " : {
         " all " :  " 전체 " ,
         " today " :  " 오늘 " ,
         " yesterday " :  " 어제 " ,
         " last7_days " :  " 최근 7일 " ,
         " this_week " :  " 이번 주 " ,
         " this_month " :  " 이번 달 " ,
         " last_month " :  " 지난 달 " ,
         " custom " :  " 기간 선택 " ,
         " invalid_date_range " :  " 종료일은 시작일 이후여야 합니다 " 
       }
    }
  },
   " main " : { ... }
}

Translation Code Generation#

After Modifying Translation Files#

# Regenerate translation code
cd shared/i10n  & &   dart run slang

# Or use melos command
melos run generate:locale

Generated Files#

shared/i10n/lib/src/translations/
├── translations.g.dart         # Base interface
├── translations_ko.g.dart      # Korean
├── translations_en.g.dart      # English
└── ... (files for each language)

Usage Examples#

Simple Text#

Text(context.i10n.common.save)
Text(context.i10n.console.sales_analysis.period.all)

Parameterized Translations#

// JSON definition (using $ format)
// "greeting": "안녕하세요, $name님!"

// Dart usage
Text(context.i10n.common.greeting(name: user.name))

Pluralization#

// JSON definition (using $ format)
// "items": {
//   "one": "$count개 항목",
//   "other": "$count개 항목들"
// }

// Dart usage
Text(context.i10n.common.items(count: items.length))

Important Notes#

When adding new keys: Must add to all language JSON files
Key naming: Always use snake_case
Code generation: Run dart run slang after modifying JSON files
API selection: Use only context.i10n (translations is prohibited)
Parameter format: Use $param format (curly braces {param} are prohibited)
- ✅ "greeting": "안녕하세요, $name님!"
- ❌ "greeting": "안녕하세요, {name}님!" (causes errors)
Parameter name consistency: Use the same parameter names across all language files
- Example: $maxSizeMB (must be identical in all languages)

CLAUDE.md - Overall project guide
Slang Official Documentation