@buivietphi/skill-mobile-mt 2.0.1 → 2.1.0

package/shared/i18n-localization.md

@@ -0,0 +1,426 @@
+# Mobile i18n & Localization
+
+> Multi-language support for React Native, Flutter, iOS, Android.
+> Covers: setup, translation management, RTL, date/number formatting, dynamic locale switching.
+
+---
+
+## Decision Matrix — Pick Your Stack
+
+```
+PLATFORM        → RECOMMENDED LIBRARY
+──────────────────────────────────────────────────────────────────
+React Native    → i18next + react-i18next (most popular, flexible)
+                  OR expo-localization + custom (Expo projects)
+
+Flutter         → slang (type-safe, code generation) ← recommended
+                  OR flutter_localizations + .arb files (official)
+                  OR easy_localization (simple)
+
+iOS Native      → .xcstrings / Localizable.strings (built-in Xcode)
+Android Native  → strings.xml per locale (built-in Android Studio)
+```
+
+---
+
+## React Native — i18next
+
+### Setup
+
+```bash
+npm install i18next react-i18next
+npm install @react-native-async-storage/async-storage  # for locale persistence
+# or with expo:
+npx expo install expo-localization
+```
+
+### File Structure
+
+```
+src/
+├── i18n/
+│   ├── index.ts              ← i18next init
+│   ├── en.json               ← English (base language)
+│   ├── vi.json               ← Vietnamese
+│   ├── ja.json               ← Japanese
+│   ├── ar.json               ← Arabic (RTL)
+│   └── types.ts              ← TypeScript type for translation keys
+```
+
+### Translation Files
+
+```json
+// i18n/en.json
+{
+  "common": {
+    "ok": "OK",
+    "cancel": "Cancel",
+    "loading": "Loading...",
+    "error": "Something went wrong",
+    "retry": "Try again",
+    "empty": "No results found"
+  },
+  "auth": {
+    "login": "Login",
+    "logout": "Logout",
+    "email": "Email address",
+    "password": "Password",
+    "forgotPassword": "Forgot password?",
+    "errors": {
+      "invalidEmail": "Please enter a valid email",
+      "wrongPassword": "Incorrect password"
+    }
+  },
+  "profile": {
+    "title": "My Profile",
+    "greeting": "Hello, {{name}}!",
+    "itemCount": "{{count}} item",
+    "itemCount_other": "{{count}} items"
+  }
+}
+```
+
+```json
+// i18n/vi.json
+{
+  "common": {
+    "ok": "Đồng ý",
+    "cancel": "Hủy",
+    "loading": "Đang tải...",
+    "error": "Có lỗi xảy ra",
+    "retry": "Thử lại",
+    "empty": "Không có kết quả"
+  },
+  "auth": {
+    "login": "Đăng nhập",
+    "logout": "Đăng xuất",
+    "email": "Địa chỉ email",
+    "password": "Mật khẩu",
+    "forgotPassword": "Quên mật khẩu?",
+    "errors": {
+      "invalidEmail": "Vui lòng nhập email hợp lệ",
+      "wrongPassword": "Mật khẩu không đúng"
+    }
+  },
+  "profile": {
+    "title": "Hồ sơ của tôi",
+    "greeting": "Xin chào, {{name}}!",
+    "itemCount": "{{count}} mục"
+  }
+}
+```
+
+### i18next Init
+
+```typescript
+// i18n/index.ts
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import * as Localization from 'expo-localization';
+import MMKV from '../storage'; // your MMKV wrapper
+
+import en from './en.json';
+import vi from './vi.json';
+import ar from './ar.json';
+
+const LANGUAGE_KEY = 'user_language';
+
+export const SUPPORTED_LANGUAGES = ['en', 'vi', 'ja', 'ar'] as const;
+export type Language = typeof SUPPORTED_LANGUAGES[number];
+
+// Get saved or device language
+const savedLang = MMKV.getString(LANGUAGE_KEY);
+const deviceLang = Localization.getLocales()[0]?.languageCode ?? 'en';
+const initialLang = savedLang ?? (SUPPORTED_LANGUAGES.includes(deviceLang as Language) ? deviceLang : 'en');
+
+i18n.use(initReactI18next).init({
+  resources: { en: { translation: en }, vi: { translation: vi }, ar: { translation: ar } },
+  lng: initialLang,
+  fallbackLng: 'en',
+  interpolation: { escapeValue: false },
+});
+
+export function changeLanguage(lang: Language) {
+  i18n.changeLanguage(lang);
+  MMKV.setString(LANGUAGE_KEY, lang);  // persist choice
+}
+
+export default i18n;
+```
+
+### Usage in Components
+
+```typescript
+import { useTranslation } from 'react-i18next';
+import { I18nManager } from 'react-native';
+
+export function ProfileScreen() {
+  const { t, i18n } = useTranslation();
+  const isRTL = I18nManager.isRTL;
+
+  return (
+    <View style={[styles.container, isRTL && styles.rtl]}>
+      <Text>{t('profile.title')}</Text>
+      <Text>{t('profile.greeting', { name: 'Phi' })}</Text>
+      <Text>{t('profile.itemCount', { count: 5 })}</Text>
+
+      {/* Language switcher */}
+      <Button title="Tiếng Việt" onPress={() => changeLanguage('vi')} />
+      <Button title="English" onPress={() => changeLanguage('en')} />
+    </View>
+  );
+}
+
+// TypeScript type-safe keys (optional but recommended)
+// Generate from en.json with i18next-resources-for-ts
+```
+
+### RTL Support (Arabic, Hebrew)
+
+```typescript
+// App.tsx — apply RTL on init
+import { I18nManager } from 'react-native';
+import * as Updates from 'expo-updates';
+
+function applyRTL(language: string) {
+  const isRTL = language === 'ar' || language === 'he';
+
+  if (I18nManager.isRTL !== isRTL) {
+    I18nManager.allowRTL(isRTL);
+    I18nManager.forceRTL(isRTL);
+    // Requires reload to take effect
+    Updates.reloadAsync(); // Expo
+    // RNRestart.Restart(); // react-native-restart (bare RN)
+  }
+}
+
+// RTL-aware styles
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: I18nManager.isRTL ? 'row-reverse' : 'row',
+  },
+  text: {
+    textAlign: I18nManager.isRTL ? 'right' : 'left',
+    writingDirection: I18nManager.isRTL ? 'rtl' : 'ltr',
+  },
+});
+```
+
+### Date / Number Formatting
+
+```typescript
+// Use Intl API (built into Hermes/V8)
+const locale = i18n.language;
+
+// Date
+const formatDate = (date: Date) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' }).format(date);
+
+// Number / Currency
+const formatCurrency = (amount: number, currency = 'USD') =>
+  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);
+
+// Relative time (2 days ago, in 3 hours)
+const formatRelative = (date: Date) =>
+  new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(
+    Math.round((date.getTime() - Date.now()) / 86400000), 'day'
+  );
+
+// Usage
+formatDate(new Date());        // "Jan 15, 2025, 2:30 PM"
+formatCurrency(99.99);         // "$99.99" / "99,99 €"
+formatRelative(yesterday);     // "yesterday" / "hôm qua"
+```
+
+---
+
+## Flutter — slang (Recommended)
+
+### Setup
+
+```yaml
+# pubspec.yaml
+dependencies:
+  flutter_localizations:
+    sdk: flutter
+  slang: ^4.0.0
+  slang_flutter: ^4.0.0
+
+dev_dependencies:
+  slang_build_runner: ^4.0.0
+  build_runner: ^2.0.0
+
+flutter:
+  generate: true
+```
+
+### Translation Files
+
+```json
+// assets/i18n/en.i18n.json
+{
+  "common": {
+    "ok": "OK",
+    "cancel": "Cancel",
+    "loading": "Loading..."
+  },
+  "auth": {
+    "login": "Login",
+    "greeting": "Hello, $name!",
+    "itemCount(n)": {
+      "one": "$n item",
+      "other": "$n items"
+    }
+  }
+}
+```
+
+```json
+// assets/i18n/vi.i18n.json
+{
+  "common": {
+    "ok": "Đồng ý",
+    "cancel": "Hủy",
+    "loading": "Đang tải..."
+  },
+  "auth": {
+    "login": "Đăng nhập",
+    "greeting": "Xin chào, $name!",
+    "itemCount(n)": "$n mục"
+  }
+}
+```
+
+### Generate + Use
+
+```bash
+dart run build_runner build
+```
+
+```dart
+// main.dart
+import 'package:flutter_localizations/flutter_localizations.dart';
+import 'i18n/strings.g.dart';  // generated
+
+void main() {
+  WidgetsFlutterBinding.ensureInitialized();
+  LocaleSettings.useDeviceLocale();  // or .setLocale(AppLocale.vi)
+  runApp(TranslationProvider(child: MyApp()));
+}
+
+class MyApp extends StatelessWidget {
+  Widget build(BuildContext context) => MaterialApp(
+    locale: TranslationProvider.of(context).flutterLocale,
+    supportedLocales: AppLocaleUtils.supportedLocales,
+    localizationsDelegates: GlobalMaterialLocalizations.delegates,
+    home: HomeScreen(),
+  );
+}
+
+// Usage — fully type-safe, autocomplete
+final t = Translations.of(context);
+
+Text(t.common.ok)
+Text(t.auth.greeting(name: 'Phi'))
+Text(t.auth.itemCount(n: 5))
+
+// Change language
+LocaleSettings.setLocale(AppLocale.vi);
+```
+
+---
+
+## iOS Native (Xcode .xcstrings)
+
+```
+Localizable.xcstrings (modern, Xcode 15+):
+  - Edit in Xcode string catalog UI
+  - Automatic plural rules per language
+  - Supports all Apple platforms
+
+File structure:
+  App/
+  ├── en.lproj/Localizable.xcstrings  ← base language
+  ├── vi.lproj/Localizable.xcstrings
+  └── ar.lproj/Localizable.xcstrings
+```
+
+```swift
+// Usage
+Text(String(localized: "auth.login"))  // SwiftUI (auto-localizes)
+label.text = NSLocalizedString("auth.login", comment: "")  // UIKit
+
+// With interpolation
+Text("profile.greeting \(userName)")
+// Localizable.xcstrings: "profile.greeting %@" → "Xin chào, %@!"
+
+// Date/Number formatting
+let formatted = Date().formatted(.dateTime.month(.wide).day().year())
+let price = amount.formatted(.currency(code: "VND").locale(Locale(identifier: "vi_VN")))
+```
+
+---
+
+## Android Native (strings.xml)
+
+```xml
+<!-- res/values/strings.xml (English, default) -->
+<resources>
+  <string name="common_ok">OK</string>
+  <string name="auth_login">Login</string>
+  <string name="profile_greeting">Hello, %s!</string>
+  <plurals name="profile_item_count">
+    <item quantity="one">%d item</item>
+    <item quantity="other">%d items</item>
+  </plurals>
+</resources>
+
+<!-- res/values-vi/strings.xml (Vietnamese) -->
+<resources>
+  <string name="common_ok">Đồng ý</string>
+  <string name="auth_login">Đăng nhập</string>
+  <string name="profile_greeting">Xin chào, %s!</string>
+  <plurals name="profile_item_count">
+    <item quantity="other">%d mục</item>
+  </plurals>
+</resources>
+```
+
+```kotlin
+// Usage
+getString(R.string.auth_login)
+getString(R.string.profile_greeting, "Phi")
+resources.getQuantityString(R.plurals.profile_item_count, 5, 5)
+```
+
+---
+
+## i18n Checklist
+
+```
+SETUP:
+  □ Translation keys are namespaced (auth.login, not just "login")
+  □ Base language file has ALL keys
+  □ Missing key fallback configured (falls back to English)
+  □ Language preference persisted on device (MMKV/SharedPreferences)
+  □ Language detected from device locale on first launch
+
+CONTENT:
+  □ No hardcoded strings in components (all through t() / getString)
+  □ Plurals handled correctly (1 item vs 2 items)
+  □ Interpolation used for dynamic values (name, count)
+  □ Date/number/currency formatted per locale (Intl API)
+
+RTL (if supporting Arabic/Hebrew):
+  □ I18nManager.forceRTL() applied and app reloaded
+  □ flexDirection mirrors on RTL
+  □ textAlign mirrors on RTL
+  □ Icons and chevrons mirror on RTL
+  □ Back navigation arrow mirrors on RTL
+
+TESTING:
+  □ Test with locale set to each supported language
+  □ Test with system language set to unsupported → falls back to English
+  □ Test RTL layout on Arabic device or simulator
+  □ Test long strings (German/Finnish) don't break UI layout
+```

package/shared/prompt-engineering.md

@@ -64,40 +64,138 @@
 ```xml
 <think>
 BUG: [description]
-FILE: [path]
+ERROR MESSAGE: [paste exact error]
+
+⛔ STOP — CLASSIFY + SEARCH PROJECT FIRST (before ANY analysis):
+
+<error_classification>
+  TYPE: [RUNTIME CRASH / BUILD ERROR / TYPE MISMATCH / NETWORK ERROR /
+         RENDER ERROR / NAVIGATION ERROR / PERFORMANCE / STATE ERROR /
+         NATIVE ERROR / MEMORY ERROR / INVESTIGATION]
+
+  SEARCH STRATEGY based on type:
+  → RUNTIME/STATE/RENDER/NAVIGATION → Search src/ FIRST → then trace outward
+  → BUILD/NATIVE                    → Search config files FIRST (tsconfig/gradle/Pod/pubspec)
+  → NETWORK/API                     → Search API service files → then .env → then interceptors
+  → INVESTIGATION                   → Search by feature name → read → report (don't fix yet)
+
+  If complex bug → Read shared/debugging-intelligence.md for pattern match
+</error_classification>
+
+<project_search>
+  STEP 1: Extract keywords from error:
+  → File/path in stack trace: [extract]
+  → Function/class/component name: [extract]
+  → Module/package name: [extract]
+  → Line number: [extract if available]
+  → Error code / HTTP status: [extract if available]
+
+  STEP 2: Filter noise from log (if user pasted log):
+  → SKIP: node_modules/*, React internals, engine frames
+  → FOCUS: lines with src/ paths, "Error:", "Caused by:", YOUR component names
+
+  STEP 3: Search project source code (MANDATORY):
+  → Grep "[keyword]" src/             ← ALWAYS start here (unless BUILD error)
+  → Grep "[function_name]" src/       ← find the actual function
+  → Glob "**/*[ComponentName]*"       ← find the actual file
+  → Results: [list files found]
+
+  STEP 4: Read matched files (TOP 3-5):
+  → Read [file1] — [what I found: actual code, types, imports]
+  → Read [file2] — [what I found: related logic, callers]
+  → Read [file3] — [what I found: state/store connected to this]
+
+  ⛔ If I skipped Step 1-4 → GO BACK AND DO THEM NOW
+  ⛔ If I found 0 results in src/ → widen: lib/ → app/ → project root
+</project_search>
 
 <source_verification>
-  ⚠️ BEFORE analyzing — verify I have real data:
-  - [ ] Read the actual file (not guessing from error message)
-  - [ ] Verified function/class names exist (grep)
+  ⚠️ Verify I have REAL project data (not assumptions):
+  - [ ] Classified error type and picked correct search strategy
+  - [ ] Filtered noise from log (if applicable)
+  - [ ] Searched src/ with Grep for error keywords → found files
+  - [ ] Read the actual file(s) where bug occurs
+  - [ ] Verified function/class names exist in project (grep result)
   - [ ] Checked package versions in package.json/pubspec.yaml
   - [ ] Identified data types from actual code (not assumed)
+  - [ ] Traced the call chain: who calls this → what it returns
 </source_verification>
 
-<context_needed>
-  - Read [file] to understand current implementation
-  - Grep for similar patterns: grep "[pattern]" src/
-  - Check imports and dependencies
-</context_needed>
-
-<root_cause>
-  [Analyze AFTER loading context - don't guess]
-  - What code is executed?
-  - What values are passed?
-  - What conditions are checked?
-  SOURCE: [file:line where the bug is — cite exact location]
-</root_cause>
+<root_cause_tracing>
+  ⛔ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+
+  STEP 1 — IMMEDIATE CAUSE (what throws):
+  - Error type: [from classification above]
+  - Crash/error at: [file:line from project search]
+  - What code does at that line: [describe from reading]
+  - What value is wrong: [actual vs expected]
+
+  STEP 2 — TRACE BACKWARD (what called this):
+  - Who calls this function? → [grep callers in src/]
+  - What data does caller pass? → [trace data origin]
+  - Go up one level: who calls the caller? → [trace further]
+
+  STEP 3 — ROOT CAUSE (where chain breaks):
+  - Root cause at: [file:line — where correct data becomes incorrect]
+  - WHY it fails: [based on actual code read, NOT guess]
+  - Does this match a known pattern? → [check debugging-intelligence.md if loaded]
+  - Does root cause explain ALL symptoms? YES/NO
+    → If NO → theory is wrong → re-trace from Step 2
+</root_cause_tracing>
+
+<working_example>
+  Search for similar working code in SAME project:
+  → Grep for similar pattern that works: [search term]
+  → Found working example at: [file:line] (or "none found")
+  → Differences between broken vs working:
+    1. [difference]
+    2. [difference]
+  → The fix should align broken code with working pattern
+</working_example>
+
+<hypothesis>
+  ⛔ 1 HYPOTHESIS → 1 MINIMAL CHANGE → VERIFY
+
+  HYPOTHESIS: [specific theory based on root cause]
+  CHANGE: [smallest possible change to test this — 1 change only]
+  EXPECTED RESULT: [what should happen if hypothesis is correct]
+
+  ⛔ If this fails → REVERT → form NEW hypothesis (never stack fixes)
+  ⛔ If 3 hypotheses fail → STOP → question architecture
+</hypothesis>
 
 <fix>
-  [Specific change with code snippet]
+  [Specific change with code snippet — before → after]
 
   WHY IT WORKS:
-  [Explain the fix based on root cause]
+  [Explain based on root cause tracing — not guess]
   SOURCE: [where this fix pattern comes from — project code / skill file / official docs]
+
+  DEFENSE IN DEPTH (make bug structurally impossible):
+  - Layer 1 (input): [validation added]
+  - Layer 2 (state): [guard added]
+  - Layer 3 (render): [null check / fallback added]
 </fix>
 
+<verification>
+  ⛔ NO COMPLETION CLAIMS WITHOUT EVIDENCE
+
+  🚩 Anti-rationalization check:
+  - Am I saying "should work now" without running it? → RUN IT
+  - Am I "confident" without evidence? → PROVE IT
+  - Am I stacking 3+ changes? → REVERT. 1 change only.
+
+  Evidence:
+  - [ ] Fix addresses root cause (not just symptoms)
+  - [ ] All symptoms explained by this root cause
+  - [ ] Working example pattern followed (if found)
+  - [ ] Defense-in-depth added at [N] layers
+  - [ ] Side effects checked (grep for other callers)
+  - [ ] Both platforms considered (iOS + Android)
+</verification>
+
 <side_effects>
-  - Files that import this: [list after grep]
+  - Files that import this: [list from grep results]
   - Tests affected: [list]
   - Platform-specific: iOS [impact] / Android [impact]
 </side_effects>
@@ -116,6 +214,64 @@ FILE: [path]
 </think>
 ```
 
+### Diagnostic Scan (user unsure / vague / "check this for me")
+
+```xml
+<think>
+USER SAID: [what user described or asked — could be vague]
+AREA: [extract: screen name / feature name / module name / file name]
+
+<area_identification>
+  What did user mention or show?
+  → Screen/feature name: [extract from user's words]
+  → File pasted/referenced: [if any]
+  → Behavior described: [if any]
+  → If unclear → I should ask: "Which screen or feature should I check?"
+</area_identification>
+
+<project_search>
+  Search broadly for this area:
+  → Grep "[feature]" src/            → found: [list files]
+  → Glob "**/*[ScreenName]*"         → found: [list files]
+  → Also search: related hooks, services, stores, utils
+  → Total files to scan: [N files]
+</project_search>
+
+<diagnostic_scan>
+  For EACH file, run the checklist:
+
+  FILE: [file1:path]
+  □ Crash risks:    [findings or "clean"]
+  □ Memory leaks:   [findings or "clean"]
+  □ Race conditions: [findings or "clean"]
+  □ Security:       [findings or "clean"]
+  □ Performance:    [findings or "clean"]
+  □ UX/states:      [findings or "clean"]
+  □ Data flow:      [trace API → state → render — any break?]
+  □ Edge cases:     [empty data? error response? offline? slow?]
+
+  FILE: [file2:path]
+  □ ... (repeat for each file)
+</diagnostic_scan>
+
+<report>
+  Scanned: [N files] in [area name]
+
+  🔴 Issues found:
+    1. [SEVERITY] [file:line] — [description]
+    2. [SEVERITY] [file:line] — [description]
+
+  🟡 Suspicious (might be intentional):
+    1. [file:line] — [what looks off and why]
+
+  ✅ Looks good:
+    - [aspect that's well-implemented]
+
+  Recommendation: [what to fix first / what to investigate deeper]
+</report>
+</think>
+```
+
 **Example:**
 ```xml
 <think>