appiq-solution 1.2.0 → 1.3.0

package/flutter/punkt.claude/punkt.claude/commands/feature-localization.md

@@ -0,0 +1,427 @@
+# Localization Development Command
+
+Develops complete localization support for a feature in all 5 supported languages following VoicePilot patterns.
+
+**Usage:** `feature-localization [FEATURE_NAME] [FEATURE_DESCRIPTION]`
+
+**Example:** `feature-localization project-favorites "Allow users to mark projects as favorites and view them in a separate list"`
+
+## Pre-Execution Checklist
+
+1. **Check Channel Status**: Read `/Users/vapps-it/Projects/voicepilot/.claude/channel.md`
+2. **Verify Dependencies**: Ensure UI layer is completed (contains all text that needs translation)
+3. **Update Channel**: Mark Localization status as "IN_PROGRESS" and assign agent
+4. **Check Blockers**: Verify UI layer provides all text content for translation
+
+## Implementation Process
+
+### Phase 1: Analysis & Text Extraction
+
+1. **Study Existing Localization Patterns**:
+   - Analyze `lib/l10n/` structure and existing ARB files
+   - Review how translations are used in existing UI components
+   - Check naming conventions for translation keys
+   - Study context usage and parameter handling
+
+2. **Extract All Text from UI Layer**:
+   - Scan all screen files for hardcoded text
+   - Identify button labels, titles, descriptions, and error messages
+   - Find placeholder text, validation messages, and tooltips
+   - Collect success messages, confirmation dialogs, and prompts
+
+3. **Plan Translation Keys**:
+   - Design consistent key naming following existing patterns
+   - Group related translations logically
+   - Plan for pluralization and context variations
+   - Identify parameters and interpolation needs
+
+4. **Update Channel**: Add localization requirements to channel.md
+
+### Phase 2: English Base Translations
+
+1. **Analyze Existing ARB Structure** (`lib/l10n/app_en.arb`):
+   ```json
+   {
+     "@@locale": "en",
+     "@@last_modified": "2024-01-01T00:00:00.000Z",
+     
+     // Existing keys...
+     
+     // Feature-specific keys (add at the end)
+     "[featureName]Title": "Feature Title",
+     "@[featureName]Title": {
+       "description": "Title for the [feature name] screen"
+     },
+     
+     "[featureName]Description": "Feature description text",
+     "@[featureName]Description": {
+       "description": "Description text for [feature name] functionality"
+     },
+     
+     "[featureName]CreateButton": "Create New",
+     "@[featureName]CreateButton": {
+       "description": "Button text to create a new [feature name] item"
+     },
+     
+     "[featureName]SearchHint": "Search [feature name]...",
+     "@[featureName]SearchHint": {
+       "description": "Placeholder text for [feature name] search field"
+     },
+     
+     "[featureName]LoadingMessage": "Loading [feature name]...",
+     "@[featureName]LoadingMessage": {
+       "description": "Message displayed while loading [feature name] data"
+     },
+     
+     "[featureName]ErrorTitle": "Error Loading [Feature Name]",
+     "@[featureName]ErrorTitle": {
+       "description": "Title for error dialog when [feature name] fails to load"
+     },
+     
+     "[featureName]ErrorMessage": "Unable to load [feature name]. Please try again.",
+     "@[featureName]ErrorMessage": {
+       "description": "Error message when [feature name] data cannot be loaded"
+     },
+     
+     "[featureName]EmptyStateTitle": "No [Feature Name] Found",
+     "@[featureName]EmptyStateTitle": {
+       "description": "Title shown when no [feature name] items exist"
+     },
+     
+     "[featureName]EmptyStateMessage": "You haven't created any [feature name] items yet. Tap the button below to get started.",
+     "@[featureName]EmptyStateMessage": {
+       "description": "Message shown when no [feature name] items exist"
+     },
+     
+     "[featureName]DeleteConfirmTitle": "Delete [Feature Name]",
+     "@[featureName]DeleteConfirmTitle": {
+       "description": "Title for delete confirmation dialog"
+     },
+     
+     "[featureName]DeleteConfirmMessage": "Are you sure you want to delete this [feature name]? This action cannot be undone.",
+     "@[featureName]DeleteConfirmMessage": {
+       "description": "Confirmation message for deleting [feature name] item"
+     },
+     
+     "[featureName]SuccessCreated": "[Feature Name] created successfully",
+     "@[featureName]SuccessCreated": {
+       "description": "Success message when [feature name] item is created"
+     },
+     
+     "[featureName]SuccessUpdated": "[Feature Name] updated successfully",
+     "@[featureName]SuccessUpdated": {
+       "description": "Success message when [feature name] item is updated"
+     },
+     
+     "[featureName]SuccessDeleted": "[Feature Name] deleted successfully",
+     "@[featureName]SuccessDeleted": {
+       "description": "Success message when [feature name] item is deleted"
+     },
+     
+     // Parameterized translations
+     "[featureName]ItemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
+     "@[featureName]ItemCount": {
+       "description": "Shows count of [feature name] items",
+       "placeholders": {
+         "count": {
+           "type": "int",
+           "format": "compact"
+         }
+       }
+     },
+     
+     "[featureName]LastUpdated": "Last updated {timeAgo}",
+     "@[featureName]LastUpdated": {
+       "description": "Shows when [feature name] was last updated",
+       "placeholders": {
+         "timeAgo": {
+           "type": "String"
+         }
+       }
+     },
+     
+     "[featureName]CreatedBy": "Created by {userName}",
+     "@[featureName]CreatedBy": {
+       "description": "Shows who created the [feature name] item",
+       "placeholders": {
+         "userName": {
+           "type": "String"
+         }
+       }
+     }
+   }
+   ```
+
+### Phase 3: German Translations
+
+2. **Add German Translations** (`lib/l10n/app_de.arb`):
+   ```json
+   {
+     "@@locale": "de",
+     "@@last_modified": "2024-01-01T00:00:00.000Z",
+     
+     // Existing keys...
+     
+     // Feature-specific German translations
+     "[featureName]Title": "Funktionstitel",
+     "[featureName]Description": "Funktionsbeschreibungstext",
+     "[featureName]CreateButton": "Neu erstellen",
+     "[featureName]SearchHint": "[Feature Name] suchen...",
+     "[featureName]LoadingMessage": "[Feature Name] wird geladen...",
+     "[featureName]ErrorTitle": "Fehler beim Laden von [Feature Name]",
+     "[featureName]ErrorMessage": "[Feature Name] konnte nicht geladen werden. Bitte versuchen Sie es erneut.",
+     "[featureName]EmptyStateTitle": "Keine [Feature Name] gefunden",
+     "[featureName]EmptyStateMessage": "Sie haben noch keine [Feature Name]-Elemente erstellt. Tippen Sie auf die Schaltfläche unten, um zu beginnen.",
+     "[featureName]DeleteConfirmTitle": "[Feature Name] löschen",
+     "[featureName]DeleteConfirmMessage": "Sind Sie sicher, dass Sie diese [Feature Name] löschen möchten? Diese Aktion kann nicht rückgängig gemacht werden.",
+     "[featureName]SuccessCreated": "[Feature Name] erfolgreich erstellt",
+     "[featureName]SuccessUpdated": "[Feature Name] erfolgreich aktualisiert",
+     "[featureName]SuccessDeleted": "[Feature Name] erfolgreich gelöscht",
+     "[featureName]ItemCount": "{count, plural, =0{Keine Elemente} =1{1 Element} other{{count} Elemente}}",
+     "[featureName]LastUpdated": "Zuletzt aktualisiert {timeAgo}",
+     "[featureName]CreatedBy": "Erstellt von {userName}"
+   }
+   ```
+
+### Phase 4: Russian Translations
+
+3. **Add Russian Translations** (`lib/l10n/app_ru.arb`):
+   ```json
+   {
+     "@@locale": "ru",
+     "@@last_modified": "2024-01-01T00:00:00.000Z",
+     
+     // Existing keys...
+     
+     // Feature-specific Russian translations
+     "[featureName]Title": "Название функции",
+     "[featureName]Description": "Описание функциональности",
+     "[featureName]CreateButton": "Создать новый",
+     "[featureName]SearchHint": "Поиск [feature name]...",
+     "[featureName]LoadingMessage": "Загрузка [feature name]...",
+     "[featureName]ErrorTitle": "Ошибка загрузки [Feature Name]",
+     "[featureName]ErrorMessage": "Не удалось загрузить [feature name]. Пожалуйста, попробуйте снова.",
+     "[featureName]EmptyStateTitle": "[Feature Name] не найдено",
+     "[featureName]EmptyStateMessage": "Вы еще не создали ни одного элемента [feature name]. Нажмите кнопку ниже, чтобы начать.",
+     "[featureName]DeleteConfirmTitle": "Удалить [Feature Name]",
+     "[featureName]DeleteConfirmMessage": "Вы уверены, что хотите удалить этот [feature name]? Это действие нельзя отменить.",
+     "[featureName]SuccessCreated": "[Feature Name] успешно создан",
+     "[featureName]SuccessUpdated": "[Feature Name] успешно обновлен",
+     "[featureName]SuccessDeleted": "[Feature Name] успешно удален",
+     "[featureName]ItemCount": "{count, plural, =0{Нет элементов} =1{1 элемент} few{{count} элемента} other{{count} элементов}}",
+     "[featureName]LastUpdated": "Последнее обновление {timeAgo}",
+     "[featureName]CreatedBy": "Создано пользователем {userName}"
+   }
+   ```
+
+### Phase 5: Turkish Translations
+
+4. **Add Turkish Translations** (`lib/l10n/app_tr.arb`):
+   ```json
+   {
+     "@@locale": "tr",
+     "@@last_modified": "2024-01-01T00:00:00.000Z",
+     
+     // Existing keys...
+     
+     // Feature-specific Turkish translations
+     "[featureName]Title": "Özellik Başlığı",
+     "[featureName]Description": "Özellik açıklama metni",
+     "[featureName]CreateButton": "Yeni Oluştur",
+     "[featureName]SearchHint": "[Feature name] ara...",
+     "[featureName]LoadingMessage": "[Feature name] yükleniyor...",
+     "[featureName]ErrorTitle": "[Feature Name] Yükleme Hatası",
+     "[featureName]ErrorMessage": "[Feature name] yüklenemedi. Lütfen tekrar deneyin.",
+     "[featureName]EmptyStateTitle": "[Feature Name] Bulunamadı",
+     "[featureName]EmptyStateMessage": "Henüz hiç [feature name] öğesi oluşturmadınız. Başlamak için aşağıdaki düğmeye dokunun.",
+     "[featureName]DeleteConfirmTitle": "[Feature Name] Sil",
+     "[featureName]DeleteConfirmMessage": "Bu [feature name] öğesini silmek istediğinizden emin misiniz? Bu işlem geri alınamaz.",
+     "[featureName]SuccessCreated": "[Feature Name] başarıyla oluşturuldu",
+     "[featureName]SuccessUpdated": "[Feature Name] başarıyla güncellendi",
+     "[featureName]SuccessDeleted": "[Feature Name] başarıyla silindi",
+     "[featureName]ItemCount": "{count, plural, =0{Öğe yok} =1{1 öğe} other{{count} öğe}}",
+     "[featureName]LastUpdated": "Son güncelleme {timeAgo}",
+     "[featureName]CreatedBy": "{userName} tarafından oluşturuldu"
+   }
+   ```
+
+### Phase 6: Arabic Translations
+
+5. **Add Arabic Translations** (`lib/l10n/app_ar.arb`):
+   ```json
+   {
+     "@@locale": "ar",
+     "@@last_modified": "2024-01-01T00:00:00.000Z",
+     
+     // Existing keys...
+     
+     // Feature-specific Arabic translations (RTL support)
+     "[featureName]Title": "عنوان الميزة",
+     "[featureName]Description": "نص وصف الميزة",
+     "[featureName]CreateButton": "إنشاء جديد",
+     "[featureName]SearchHint": "البحث في [feature name]...",
+     "[featureName]LoadingMessage": "جاري تحميل [feature name]...",
+     "[featureName]ErrorTitle": "خطأ في تحميل [Feature Name]",
+     "[featureName]ErrorMessage": "تعذر تحميل [feature name]. يرجى المحاولة مرة أخرى.",
+     "[featureName]EmptyStateTitle": "لم يتم العثور على [Feature Name]",
+     "[featureName]EmptyStateMessage": "لم تقم بإنشاء أي عناصر [feature name] بعد. اضغط على الزر أدناه للبدء.",
+     "[featureName]DeleteConfirmTitle": "حذف [Feature Name]",
+     "[featureName]DeleteConfirmMessage": "هل أنت متأكد من رغبتك في حذف هذا [feature name]؟ لا يمكن التراجع عن هذا الإجراء.",
+     "[featureName]SuccessCreated": "تم إنشاء [Feature Name] بنجاح",
+     "[featureName]SuccessUpdated": "تم تحديث [Feature Name] بنجاح",
+     "[featureName]SuccessDeleted": "تم حذف [Feature Name] بنجاح",
+     "[featureName]ItemCount": "{count, plural, =0{لا توجد عناصر} =1{عنصر واحد} =2{عنصران} few{{count} عناصر} many{{count} عنصراً} other{{count} عنصر}}",
+     "[featureName]LastUpdated": "آخر تحديث {timeAgo}",
+     "[featureName]CreatedBy": "تم إنشاؤه بواسطة {userName}"
+   }
+   ```
+
+### Phase 7: Generate Localization Files
+
+6. **Run Flutter Localization Generation**:
+   ```bash
+   flutter gen-l10n
+   ```
+
+7. **Verify Generated Files**:
+   - Check `lib/l10n/app_localizations.dart` is updated
+   - Verify all new keys are available in `AppLocalizations`
+   - Test generated getter methods work correctly
+
+### Phase 8: Update UI Implementation
+
+8. **Replace Hardcoded Text in UI Components**:
+   ```dart
+   // Before (hardcoded text)
+   Text('Create New')
+   
+   // After (localized)
+   Text(l10n.[featureName]CreateButton)
+   ```
+
+9. **Update All UI Files**:
+   - Replace all hardcoded strings with l10n calls
+   - Add proper context using `AppLocalizations.of(context)`
+   - Handle parameterized translations correctly
+   - Ensure proper null safety
+
+### Phase 9: RTL Support Implementation
+
+10. **Add RTL Support for Arabic**:
+    ```dart
+    // In UI components, check for RTL
+    final isRTL = Directionality.of(context) == TextDirection.rtl;
+    
+    // Adjust icon positions for RTL
+    Row(
+      children: [
+        if (!isRTL) Icon(Icons.arrow_forward),
+        Text(l10n.[featureName]Title),
+        if (isRTL) Icon(Icons.arrow_back),
+      ],
+    )
+    
+    // Use EdgeInsets.only for RTL-aware padding
+    EdgeInsets.only(
+      left: isRTL ? 0 : 16,
+      right: isRTL ? 16 : 0,
+    )
+    ```
+
+### Phase 10: Validation & Testing
+
+11. **Validation Checklist**:
+    - [ ] All UI text is localized (no hardcoded strings)
+    - [ ] All 5 languages have complete translations
+    - [ ] Parameterized translations work correctly
+    - [ ] Pluralization works for all supported languages
+    - [ ] RTL layout works correctly for Arabic
+    - [ ] Generated localization files are complete
+    - [ ] No compilation errors after localization
+
+12. **Test Each Language**:
+    - Switch app language and verify all text displays correctly
+    - Test text overflow handling with longer translations
+    - Verify special characters and unicode support
+    - Test RTL layout behavior for Arabic
+
+## Quality Checklist
+
+### Translation Quality
+- [ ] All text properly translated (not just copy-pasted)
+- [ ] Cultural appropriateness considered
+- [ ] Consistent terminology within feature
+- [ ] Proper grammar and syntax
+- [ ] Meaningful context descriptions
+
+### Technical Implementation
+- [ ] All ARB files updated consistently
+- [ ] Generated localization files work
+- [ ] No hardcoded text remains
+- [ ] Proper parameterization used
+- [ ] RTL support implemented
+
+### User Experience
+- [ ] Text fits properly in UI elements
+- [ ] Translations are user-friendly
+- [ ] Consistent with existing app translations
+- [ ] Proper handling of text direction
+- [ ] Accessible to all target audiences
+
+## Channel Communication
+
+### Before Starting
+Update channel.md:
+```markdown
+### 🌍 Localization Status
+- **Status:** IN_PROGRESS
+- **Assigned Agent:** [YOUR_ID]
+- **Progress:** 0%
+```
+
+### During Development
+Update progress regularly:
+```markdown
+- **Progress:** [PERCENTAGE]%
+- **Languages Completed:** [LIST]
+- **Next Steps:** [CURRENT_WORK]
+```
+
+### After Completion
+Mark as completed:
+```markdown
+### 🌍 Localization Status
+- **Status:** COMPLETED
+- **Progress:** 100%
+- **Languages:** en, de, ru, tr, ar (ALL COMPLETED)
+```
+
+## Dependencies
+
+### Must be completed first:
+- UI layer (provides all text content)
+
+### Can work in parallel with:
+- Data layer (no text dependencies)
+- Business logic layer (no text dependencies)
+
+### Enables after completion:
+- Complete feature integration
+- Multi-language testing
+
+## Output Deliverables
+
+1. **Updated ARB Files**:
+   - `lib/l10n/app_en.arb` (English base)
+   - `lib/l10n/app_de.arb` (German)
+   - `lib/l10n/app_ru.arb` (Russian)
+   - `lib/l10n/app_tr.arb` (Turkish)
+   - `lib/l10n/app_ar.arb` (Arabic)
+
+2. **Generated Files**: Updated `lib/l10n/app_localizations.dart`
+
+3. **Updated UI Files**: All screen and component files with localized text
+
+4. **Updated Channel**: Progress and completion status in channel.md
+
+All text must be properly localized with complete RTL support and cultural appropriateness for all target languages.