timsquad 3.3.0 → 3.4.0

package/templates/base/skills/mobile/flutter/i18n/references/i18n-architecture.md

@@ -0,0 +1,225 @@
+---
+title: i18n Architecture & Translation Workflow
+category: reference
+source: internal
+tags: architecture, directory, workflow, ci, missing-keys, translation
+---
+
+# i18n Architecture & Translation Workflow
+
+i18n 서비스 아키텍처. 디렉토리 구조, 번역 워크플로우, CI 자동 검증, 누락 키 감지.
+
+## Key Concepts
+
+- **ARB 중심**: 모든 번역의 원본은 ARB 파일 (코드에 문자열 하드코딩 금지)
+- **코드 생성**: `flutter gen-l10n` → 타입 안전한 `AppLocalizations` 클래스 자동 생성
+- **CI 검증**: 빌드 파이프라인에서 누락 키, 미사용 키, 포맷 오류 자동 감지
+- **번역 프로세스**: 개발자 (키 추가) → 번역가 (번역) → 검수 (QA) → 머지
+
+## Directory Structure
+
+```
+lib/
+├── l10n/
+│   ├── app_en.arb                    # 기본 (template) — 모든 키 + 메타데이터
+│   ├── app_ko.arb                    # 한국어
+│   ├── app_ms.arb                    # 말레이어
+│   ├── app_id.arb                    # 인도네시아어
+│   └── app_zh.arb                    # 중국어 (간체)
+│
+├── core/
+│   └── l10n/
+│       ├── locale_notifier.dart      # LocaleNotifier (Riverpod)
+│       ├── app_locale.dart           # AppLocale enum (지원 로캘 목록)
+│       ├── l10n_extension.dart       # BuildContext.l10n extension
+│       └── locale_observer.dart      # 시스템 로캘 변경 감지
+│
+├── features/
+│   └── settings/
+│       └── presentation/
+│           └── screens/
+│               └── language_settings_screen.dart  # 언어 설정 UI
+│
+└── .dart_tool/
+    └── flutter_gen/
+        └── gen_l10n/                 # 자동 생성 (커밋 X)
+            ├── app_localizations.dart
+            ├── app_localizations_en.dart
+            ├── app_localizations_ko.dart
+            └── ...
+```
+
+## Translation Workflow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    번역 워크플로우                          │
+├──────────┬────────────────┬──────────────┬───────────────┤
+│ 1. 개발자  │  2. 번역가       │  3. 검수       │  4. 머지      │
+├──────────┼────────────────┼──────────────┼───────────────┤
+│ app_en.arb│ app_ko.arb    │ 화면 확인     │ PR 승인       │
+│ 키 추가   │ app_ms.arb    │ 문맥 확인     │ CI 통과       │
+│ @메타데이터│ app_id.arb    │ 길이 확인     │ 머지          │
+│ 설명 작성  │ 번역 작성      │ RTL 확인     │ 배포          │
+├──────────┼────────────────┼──────────────┼───────────────┤
+│ PR 생성   │ 번역 PR 생성    │ 리뷰 코멘트  │ gen-l10n 실행  │
+└──────────┴────────────────┴──────────────┴───────────────┘
+```
+
+### 단계별 상세
+
+```
+1. 개발자 (키 추가)
+   - app_en.arb에 새 키 + @메타데이터 추가
+   - description에 화면 위치, 용도, 맥락 설명
+   - placeholder에 type, example 명시
+   - 스크린샷/화면 위치 정보 첨부 (번역가 맥락 전달)
+
+2. 번역가 (번역)
+   - 각 로캘 ARB 파일에 번역 추가
+   - ICU 복수형/성별 규칙 적용 (언어별)
+   - placeholder 위치 조정 (언어 어순에 맞게)
+
+3. 검수 (QA)
+   - 실제 화면에서 번역 확인 (텍스트 잘림, 줄바꿈)
+   - RTL 레이아웃 확인 (해당 시)
+   - 복수형/성별 변형 모두 확인
+   - 문화적 적절성 확인
+
+4. 머지
+   - CI 자동 검증 통과 확인
+   - flutter gen-l10n 빌드 성공 확인
+   - 머지 후 릴리스 포함
+```
+
+## CI Automated Verification
+
+### 누락 키 감지 스크립트
+
+```bash
+#!/bin/bash
+# scripts/check_l10n.sh — CI에서 실행
+
+set -e
+
+echo "=== i18n Key Verification ==="
+
+# 1. gen-l10n 빌드 테스트
+flutter gen-l10n
+echo "✓ gen-l10n succeeded"
+
+# 2. 누락 키 체크 (template ARB 기준)
+TEMPLATE="lib/l10n/app_en.arb"
+ERRORS=0
+
+for ARB in lib/l10n/app_*.arb; do
+  if [ "$ARB" = "$TEMPLATE" ]; then continue; fi
+
+  LOCALE=$(basename "$ARB" .arb | sed 's/app_//')
+
+  # template의 비-메타 키 추출
+  TEMPLATE_KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$TEMPLATE" | sort)
+  LOCALE_KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$ARB" | sort)
+
+  # 누락 키 찾기
+  MISSING=$(comm -23 <(echo "$TEMPLATE_KEYS") <(echo "$LOCALE_KEYS"))
+  if [ -n "$MISSING" ]; then
+    echo "✗ $LOCALE: Missing keys:"
+    echo "$MISSING" | sed 's/^/    /'
+    ERRORS=$((ERRORS + 1))
+  else
+    echo "✓ $LOCALE: All keys present"
+  fi
+done
+
+if [ $ERRORS -gt 0 ]; then
+  echo "FAIL: $ERRORS locale(s) have missing keys"
+  exit 1
+fi
+
+echo "=== All i18n checks passed ==="
+```
+
+### 미사용 키 감지
+
+```bash
+#!/bin/bash
+# scripts/check_unused_l10n.sh
+
+TEMPLATE="lib/l10n/app_en.arb"
+UNUSED=0
+
+# template의 키 목록 추출
+KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$TEMPLATE")
+
+for KEY in $KEYS; do
+  # Dart 코드에서 사용 여부 확인 (.l10n.$KEY 또는 l10n.$KEY)
+  if ! grep -rq "\.$KEY" lib/ --include="*.dart" 2>/dev/null; then
+    echo "⚠ Potentially unused: $KEY"
+    UNUSED=$((UNUSED + 1))
+  fi
+done
+
+if [ $UNUSED -gt 0 ]; then
+  echo "WARNING: $UNUSED potentially unused key(s)"
+fi
+```
+
+## ARB Key Organization
+
+```json
+// 키 그룹화 전략 (featureName_ 접두사로 자연 정렬)
+{
+  "@@locale": "en",
+
+  // === Common (공통) ===
+  "common_cancelButton": "Cancel",
+  "common_confirmButton": "Confirm",
+  "common_deleteButton": "Delete",
+  "common_loadingMessage": "Loading...",
+  "common_retryButton": "Retry",
+
+  // === Error (에러) ===
+  "error_networkTimeout": "Network timeout. Please try again.",
+  "error_serverError": "Server error. Please try later.",
+  "error_unauthorized": "Please log in again.",
+
+  // === Match (매치) ===
+  "matchDetail_inviteButton": "Invite to Match",
+  "matchDetail_playerCount": "{count, plural, =0{No players} =1{1 player} other{{count} players}}",
+  "matchList_emptyState": "No matches available",
+  "matchList_title": "Available Matches",
+
+  // === Settings (설정) ===
+  "settings_languageTitle": "Language",
+  "settings_systemLanguage": "System Language"
+}
+```
+
+## Common Pitfalls
+
+1. **gen-l10n 미실행**: ARB 수정 후 코드 생성 안 하면 IDE 자동완성 미반영
+2. **@@locale 누락**: ARB 파일에 로캘 코드 없으면 파일명에서 유추 (명시 권장)
+3. **ICU 구문 오류**: 중괄호 불일치, other 누락 → gen-l10n 빌드 실패
+4. **텍스트 길이**: 독일어 등 긴 번역 → UI 레이아웃 깨짐 (Expanded/Flexible 사용)
+5. **날짜/숫자 포맷**: ARB placeholder format 미지정 → 로캘별 포맷 미적용
+6. **컨텍스트 없는 description**: 번역가가 맥락 모르면 오역 → 화면 위치/용도 필수
+7. **하드코딩된 문자열**: 로그, 에러 메시지도 ARB로 (사용자 노출 가능성)
+8. **synthetic-package 이해**: `.dart_tool/` 에 생성 → `.gitignore` 에 이미 포함 (커밋 X)
+
+## Examples
+
+### 최소 구현 체크리스트
+
+```
+[ ] pubspec.yaml: flutter_localizations + intl + generate: true
+[ ] l10n.yaml: arb-dir, template-arb-file, output-localization-file
+[ ] lib/l10n/app_en.arb: 기본 키 + @메타데이터
+[ ] lib/l10n/app_ko.arb (등): 번역 ARB
+[ ] MaterialApp: localizationsDelegates (4종) + supportedLocales
+[ ] core/l10n/: LocaleNotifier + AppLocale enum
+[ ] main.dart: SharedPreferences 초기화 + ProviderScope override
+[ ] 설정 화면: 언어 선택 UI
+[ ] CI: 누락 키 검증 스크립트
+[ ] 위젯 테스트: RTL 레이아웃 확인
+```

package/templates/base/skills/mobile/flutter/i18n/rules/arb-files.md

@@ -0,0 +1,182 @@
+---
+title: ARB File Management
+impact: CRITICAL
+impactDescription: "ARB 구조 불일치 → 빌드 실패, 키 누락 → 런타임 null, 네이밍 비일관 → 유지보수 비용 증가"
+tags: arb, app-resource-bundle, placeholder, gen-l10n, naming
+---
+
+## ARB File Management
+
+**Impact: CRITICAL (ARB 구조 불일치 → 빌드 실패, 키 누락 → 런타임 null, 네이밍 비일관 → 유지보수 비용 증가)**
+
+ARB (Application Resource Bundle) 파일 구조, @placeholder 메타데이터, 네이밍 컨벤션,
+자동 생성 워크플로우. 모든 번역의 원본 소스.
+
+### 기본 ARB 파일 구조
+
+**Incorrect (메타데이터 없는 평면 구조):**
+```json
+{
+  "hello": "Hello",
+  "welcome": "Welcome, {name}",
+  "items": "You have {count} items"
+}
+```
+
+**Correct (메타데이터 포함 구조화된 ARB):**
+```json
+{
+  "@@locale": "en",
+  "@@last_modified": "2026-02-18T10:00:00+09:00",
+
+  "appTitle": "MyApp",
+  "@appTitle": {
+    "description": "The application title shown in AppBar"
+  },
+
+  "welcomeMessage": "Welcome, {userName}!",
+  "@welcomeMessage": {
+    "description": "Greeting shown on home screen after login",
+    "placeholders": {
+      "userName": {
+        "type": "String",
+        "example": "Tim"
+      }
+    }
+  },
+
+  "matchCount": "{count, plural, =0{No matches} =1{1 match} other{{count} matches}}",
+  "@matchCount": {
+    "description": "Number of available matches",
+    "placeholders": {
+      "count": {
+        "type": "int",
+        "example": "5"
+      }
+    }
+  }
+}
+```
+
+### 키 네이밍 컨벤션
+
+```
+패턴: featureName_context_element
+
+예시:
+  ✅ matchDetail_inviteButton       → 매치 상세 화면의 초대 버튼
+  ✅ matchDetail_playerCount         → 매치 상세의 참가자 수
+  ✅ settings_languageLabel          → 설정 화면의 언어 레이블
+  ✅ common_cancelButton             → 공통 취소 버튼
+  ✅ error_networkTimeout            → 에러 메시지: 네트워크 타임아웃
+  ✅ validation_emailInvalid         → 유효성 검사: 이메일 형식 오류
+
+  ❌ invite                          → 맥락 없음 (어디서 사용?)
+  ❌ button1                         → 의미 없는 번호
+  ❌ match_detail_invite_button      → snake_case 혼용 (camelCase 사용)
+  ❌ MATCH_INVITE                    → 대문자 (camelCase 사용)
+```
+
+### 다국어 ARB 파일 관리
+
+```json
+// lib/l10n/app_en.arb (기본 — template ARB)
+{
+  "@@locale": "en",
+  "matchDetail_inviteButton": "Invite to Match",
+  "@matchDetail_inviteButton": {
+    "description": "Button to invite a player to the match"
+  },
+  "matchDetail_playerCount": "{count, plural, =0{No players} =1{1 player} other{{count} players}}",
+  "@matchDetail_playerCount": {
+    "description": "Number of players in the match",
+    "placeholders": {
+      "count": { "type": "int" }
+    }
+  }
+}
+
+// lib/l10n/app_ko.arb
+{
+  "@@locale": "ko",
+  "matchDetail_inviteButton": "매치 초대",
+  "matchDetail_playerCount": "{count, plural, =0{참가자 없음} =1{1명} other{{count}명}}"
+}
+
+// lib/l10n/app_ms.arb
+{
+  "@@locale": "ms",
+  "matchDetail_inviteButton": "Jemput ke Perlawanan",
+  "matchDetail_playerCount": "{count, plural, =0{Tiada pemain} =1{1 pemain} other{{count} pemain}}"
+}
+```
+
+### @placeholder 메타데이터
+
+```json
+{
+  "orderSummary": "Order #{orderId} — {itemCount} items, {totalPrice}",
+  "@orderSummary": {
+    "description": "Order summary displayed in confirmation screen",
+    "placeholders": {
+      "orderId": {
+        "type": "String",
+        "example": "A1234"
+      },
+      "itemCount": {
+        "type": "int",
+        "format": "compact",
+        "example": "3"
+      },
+      "totalPrice": {
+        "type": "double",
+        "format": "currency",
+        "optionalParameters": {
+          "decimalDigits": 2,
+          "symbol": "$"
+        },
+        "example": "29.99"
+      }
+    }
+  },
+
+  "lastUpdated": "Last updated: {date}",
+  "@lastUpdated": {
+    "description": "Timestamp for last data refresh",
+    "placeholders": {
+      "date": {
+        "type": "DateTime",
+        "format": "yMMMd",
+        "example": "Feb 18, 2026"
+      }
+    }
+  }
+}
+```
+
+### 자동 생성
+
+```bash
+# ARB 파일에서 Dart 코드 생성
+flutter gen-l10n
+
+# 생성 결과 (synthetic-package: true 기본):
+# .dart_tool/flutter_gen/gen_l10n/
+#   ├── app_localizations.dart         # 추상 클래스
+#   ├── app_localizations_en.dart      # English 구현
+#   └── app_localizations_ko.dart      # Korean 구현
+
+# import 경로:
+# import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+```
+
+### 규칙
+
+- `app_en.arb` → template ARB (기본), 모든 키와 `@` 메타데이터 포함
+- 번역 ARB (app_ko.arb 등) → 키와 값만 포함, `@` 메타데이터 생략 가능
+- `@@locale` → 각 ARB 파일 최상단에 로캘 코드 명시
+- 키 네이밍 → `featureName_context` camelCase, 공통 키는 `common_` 접두사
+- `@placeholder` → 모든 동적 값에 `type`, `example` 필수, 숫자/날짜는 `format` 추가
+- template ARB의 모든 키 → 번역 ARB에도 존재해야 함 (누락 시 gen-l10n 경고)
+- ARB 파일 변경 후 `flutter gen-l10n` 실행 (빌드 시 자동이지만 IDE 자동완성용)
+- description → 번역가를 위한 맥락 설명, 화면 위치/용도 명시

package/templates/base/skills/mobile/flutter/i18n/rules/locale-switching.md

@@ -0,0 +1,226 @@
+---
+title: Runtime Locale Switching
+impact: MEDIUM
+impactDescription: "전환 미지원 → 앱 재시작 필요, 영속화 누락 → 매 시작 시 시스템 로캘로 리셋"
+tags: locale, riverpod, shared-preferences, runtime, system-locale
+---
+
+## Runtime Locale Switching
+
+**Impact: MEDIUM (전환 미지원 → 앱 재시작 필요, 영속화 누락 → 매 시작 시 시스템 로캘로 리셋)**
+
+런타임 로캘 전환. Riverpod 기반 LocaleNotifier, SharedPreferences 영속화,
+시스템 로캘 감지, 앱 재시작 없이 즉시 반영.
+
+### LocaleNotifier (Riverpod)
+
+**Incorrect (전역 변수 + setState):**
+```dart
+// 전역 변수로 로캘 관리 → 위젯 트리 재빌드 불완전
+Locale currentLocale = const Locale('en');
+
+void changeLocale(Locale locale) {
+  currentLocale = locale;
+  // setState? → MaterialApp 레벨까지 전파 불가
+}
+```
+
+**Correct (Riverpod StateNotifier + 영속화):**
+```dart
+/// 지원 로캘 목록
+enum AppLocale {
+  en(Locale('en'), 'English'),
+  ko(Locale('ko'), '한국어'),
+  ms(Locale('ms'), 'Bahasa Melayu'),
+  id(Locale('id'), 'Bahasa Indonesia');
+
+  const AppLocale(this.locale, this.displayName);
+  final Locale locale;
+  final String displayName;
+
+  static AppLocale fromCode(String code) {
+    return AppLocale.values.firstWhere(
+      (l) => l.locale.languageCode == code,
+      orElse: () => AppLocale.en,
+    );
+  }
+}
+
+/// 로캘 상태 관리 + 영속화
+class LocaleNotifier extends StateNotifier<Locale?> {
+  final SharedPreferences _prefs;
+  static const _key = 'app_locale';
+
+  LocaleNotifier(this._prefs) : super(null) {
+    _loadSavedLocale();
+  }
+
+  void _loadSavedLocale() {
+    final saved = _prefs.getString(_key);
+    if (saved != null) {
+      state = AppLocale.fromCode(saved).locale;
+    }
+    // null → 시스템 로캘 사용 (MaterialApp.locale = null)
+  }
+
+  /// 로캘 변경 (즉시 반영 + 영속화)
+  Future<void> setLocale(AppLocale appLocale) async {
+    state = appLocale.locale;
+    await _prefs.setString(_key, appLocale.locale.languageCode);
+  }
+
+  /// 시스템 로캘로 리셋
+  Future<void> resetToSystem() async {
+    state = null;
+    await _prefs.remove(_key);
+  }
+
+  /// 현재 유효 로캘 (상태 또는 시스템)
+  Locale effectiveLocale(BuildContext context) {
+    return state ?? Localizations.localeOf(context);
+  }
+}
+
+/// Riverpod Providers
+final sharedPreferencesProvider = Provider<SharedPreferences>((ref) {
+  throw UnimplementedError('Override in ProviderScope');
+});
+
+final localeNotifierProvider =
+    StateNotifierProvider<LocaleNotifier, Locale?>((ref) {
+  return LocaleNotifier(ref.watch(sharedPreferencesProvider));
+});
+
+final localeProvider = Provider<Locale?>((ref) {
+  return ref.watch(localeNotifierProvider);
+});
+```
+
+### MaterialApp 연동
+
+```dart
+class MyApp extends ConsumerWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final locale = ref.watch(localeProvider);
+
+    return MaterialApp.router(
+      locale: locale,  // null → 시스템 로캘 사용
+      localizationsDelegates: const [
+        AppLocalizations.delegate,
+        GlobalMaterialLocalizations.delegate,
+        GlobalWidgetsLocalizations.delegate,
+        GlobalCupertinoLocalizations.delegate,
+      ],
+      supportedLocales: AppLocalizations.supportedLocales,
+      // 시스템 로캘과 지원 로캘 매칭 전략
+      localeResolutionCallback: (deviceLocale, supportedLocales) {
+        for (final supported in supportedLocales) {
+          if (supported.languageCode == deviceLocale?.languageCode) {
+            return supported;
+          }
+        }
+        return supportedLocales.first;  // 폴백: 첫 번째 (en)
+      },
+      routerConfig: ref.watch(routerProvider),
+    );
+  }
+}
+```
+
+### main.dart 초기화
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // SharedPreferences 초기화 (앱 시작 시 1회)
+  final prefs = await SharedPreferences.getInstance();
+
+  runApp(
+    ProviderScope(
+      overrides: [
+        sharedPreferencesProvider.overrideWithValue(prefs),
+      ],
+      child: const MyApp(),
+    ),
+  );
+}
+```
+
+### 설정 화면 UI
+
+```dart
+class LanguageSettingsScreen extends ConsumerWidget {
+  const LanguageSettingsScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final currentLocale = ref.watch(localeProvider);
+
+    return Scaffold(
+      appBar: AppBar(title: Text(context.l10n.settings_languageTitle)),
+      body: ListView(
+        children: [
+          // 시스템 로캘 옵션
+          RadioListTile<Locale?>(
+            title: Text(context.l10n.settings_systemLanguage),
+            subtitle: Text(_getSystemLocaleName(context)),
+            value: null,
+            groupValue: currentLocale,
+            onChanged: (_) {
+              ref.read(localeNotifierProvider.notifier).resetToSystem();
+            },
+          ),
+          const Divider(),
+          // 지원 로캘 목록
+          ...AppLocale.values.map((appLocale) {
+            return RadioListTile<Locale?>(
+              title: Text(appLocale.displayName),
+              value: appLocale.locale,
+              groupValue: currentLocale,
+              onChanged: (_) {
+                ref.read(localeNotifierProvider.notifier).setLocale(appLocale);
+              },
+            );
+          }),
+        ],
+      ),
+    );
+  }
+
+  String _getSystemLocaleName(BuildContext context) {
+    final systemLocale = WidgetsBinding.instance.platformDispatcher.locale;
+    return systemLocale.languageCode.toUpperCase();
+  }
+}
+```
+
+### 시스템 로캘 변경 감지
+
+```dart
+// WidgetsBindingObserver로 시스템 로캘 변경 감지
+class LocaleObserver extends WidgetsBindingObserver {
+  final VoidCallback onLocaleChanged;
+
+  LocaleObserver({required this.onLocaleChanged});
+
+  @override
+  void didChangeLocales(List<Locale>? locales) {
+    // 사용자가 "시스템 로캘 사용" 선택한 경우에만 반응
+    onLocaleChanged();
+  }
+}
+```
+
+### 규칙
+
+- `LocaleNotifier` → Riverpod StateNotifier, `Locale?` 상태 (null = 시스템 로캘)
+- `SharedPreferences` → 선택 로캘 영속화, 앱 재시작 시 복원
+- `MaterialApp.locale` → `null` 전달 시 시스템 로캘 자동 사용
+- `localeResolutionCallback` → 지원 로캘과 시스템 로캘 매칭, 미지원 시 폴백
+- 앱 재시작 없이 전환 → `locale` 변경 시 MaterialApp 재빌드 → 즉시 반영
+- "시스템 언어 사용" 옵션 → 사용자에게 항상 제공 (기본값)
+- `didChangeLocales` → 시스템 언어 변경 시 실시간 반영 (시스템 모드일 때만)