# 🇵🇹 Language Policy - Portuguese (Portugal)

---

## 📋 OVERVIEW

This document establishes the official language policy for the AI Study Assistant project. All user-facing content, UI elements, documentation, and communications must be in **Portuguese (Portugal)**.

---

## 🎯 PRIMARY LANGUAGE REQUIREMENT

### **MANDATORY LANGUAGE:**
- **Portuguese (Portugal)** - `pt_PT`
- **Locale Code:** `pt-PT`
- **Default Language:** Portuguese (Portugal)

### **SUPPORTED LANGUAGES:**
1. **Portuguese (Portugal)** - Primary language (pt-PT)
2. **English (US)** - Fallback language only (en-US)

---

## 📱 IMPLEMENTATION REQUIREMENTS

### **Flutter App Configuration:**
```dart
// main.dart
MaterialApp.router(
  locale: const Locale('pt', 'PT'), // Default to Portuguese (Portugal)
  supportedLocales: [
    Locale('pt', 'PT'), // Portuguese (Portugal) - Primary
    Locale('en', 'US'), // English (US) - Fallback
  ],
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
)
```

### **Localization Files Structure:**
```
lib/l10n/
├── app_pt.arb          # Portuguese (Portugal) - PRIMARY
├── app_en.arb          # English (US) - FALLBACK ONLY
└── app_localizations.dart
```

---

## 📝 CONTENT REQUIREMENTS

### **ALL User-Facing Content MUST be in Portuguese (Portugal):**

#### **✅ REQUIRED IN PORTUGUESE:**
- **UI Text:** Buttons, labels, titles, descriptions
- **Error Messages:** Validation errors, system messages
- **Navigation:** Menu items, route names, breadcrumbs
- **Forms:** Field labels, placeholders, help text
- **Notifications:** Push notifications, in-app alerts
- **Tooltips:** Help text, hints, descriptions
- **Loading States:** Loading messages, progress indicators
- **Success Messages:** Confirmation texts, completion messages

#### **✅ EXAMPLES:**
```
✅ CORRECT:
- "Iniciar Sessão"
- "Criar Conta"
- "Bem-vindo de volta"
- "Por favor, introduza o seu email"
- "A carregar..."

❌ INCORRECT:
- "Sign In"
- "Create Account"
- "Welcome Back"
- "Please enter your email"
- "Loading..."
```

---

## 🎨 UI/UX REQUIREMENTS

### **Text Colors for Dark Backgrounds:**
Since the app uses dark input field backgrounds, ensure proper text visibility:

```dart
// Input fields with dark backgrounds
TextStyle(
  color: AppColors.textPrimary, // Light text for dark backgrounds
  fontSize: 16,
)

// Hint text
hintStyle: TextStyle(
  color: AppColors.textHint, // Muted but visible
  fontSize: 14,
)
```

### **Contrast Requirements:**
- **Minimum Contrast Ratio:** 4.5:1 (WCAG AA)
- **Primary Text:** High contrast against backgrounds
- **Secondary Text:** Still readable but lower contrast
- **Disabled Text:** Clearly distinguishable but not interactive

---

## 📚 DOCUMENTATION REQUIREMENTS

### **All Documentation Must Be in Portuguese (Portugal):**

#### **✅ REQUIRED DOCUMENTS:**
- **User Guide** - `docs/USER_GUIDE.md`
- **API Documentation** - `docs/API_DOCUMENTATION.md`
- **Development Setup** - `docs/DEVELOPMENT_SETUP.md`
- **Contributing Guidelines** - `docs/CONTRIBUTING.md`
- **Change Log** - `docs/CHANGELOG.md`
- **Security Guide** - `docs/SECURITY_GUIDE.md`

#### **✅ CODE COMMENTS:**
- **User-Facing Features:** Comments in Portuguese
- **Business Logic:** Comments in Portuguese
- **Technical Implementation:** Comments can be in English (if necessary)
- **API Documentation:** Portuguese for public APIs

---

## 🔧 DEVELOPMENT GUIDELINES

### **When Adding New Features:**
1. **Always add Portuguese text first** to `app_pt.arb`
2. **Add English fallback** to `app_en.arb` only if necessary
3. **Test with Portuguese locale** as default
4. **Ensure proper text visibility** with current theme

### **Code Review Checklist:**
- [ ] All user-facing text is in Portuguese (Portugal)
- [ ] Text is visible with current color scheme
- [ ] Proper contrast ratios maintained
- [ ] No hardcoded English strings in UI
- [ ] Localization keys are descriptive
- [ ] Error messages are user-friendly in Portuguese

---

## 🚀 DEPLOYMENT REQUIREMENTS

### **Production Deployment:**
- **Default Language:** Portuguese (Portugal)
- **Fallback Language:** English (US)
- **Language Detection:** Auto-detect Portuguese locale
- **Testing:** Must test Portuguese (Portugal) locale

### **App Store Listings:**
- **Title:** Portuguese (Portugal)
- **Description:** Portuguese (Portugal)
- **Screenshots:** Portuguese (Portugal) UI
- **Keywords:** Portuguese terms

---

## ⚠️ EXCEPTIONS (Limited)

### **English Allowed Only For:**
- **Technical API Documentation** (internal use)
- **Code Comments** (technical implementation)
- **Variable Names** (programming standards)
- **Library Dependencies** (third-party)
- **Error Logs** (system debugging)

### **NEVER in English:**
- User-facing messages
- UI text elements
- Error messages shown to users
- Help documentation
- Marketing materials

---

## 🔄 MAINTENANCE

### **Regular Reviews:**
- **Monthly:** Check for hardcoded English strings
- **Quarterly:** Review localization completeness
- **Release:** Verify Portuguese (Portugal) quality

### **Quality Assurance:**
- **Native Speaker Review:** Portuguese (Portugal) native speaker validation
- **User Testing:** Test with Portuguese (Portugal) users
- **Accessibility:** Screen reader compatibility in Portuguese

---

## 📞 CONTACT

**Language Policy Questions:**
- **Project Lead:** Review and approve language decisions
- **Localization Team:** Handle translation and cultural adaptation
- **QA Team:** Verify language implementation quality

---

## 📋 COMPLIANCE CHECKLIST

### **Before Release:**
- [ ] All UI text in Portuguese (Portugal)
- [ ] Error messages localized
- [ ] Documentation in Portuguese (Portugal)
- [ ] Proper text contrast with dark themes
- [ ] No hardcoded English strings
- [ ] Portuguese (Portugal) set as default locale
- [ ] Fallback to English working
- [ ] Screen reader compatibility tested

---

**🇵🇹 This policy is MANDATORY for all project contributors. Violations must be corrected immediately.**

---

*Last Updated: 2024-05-06*
*Version: 1.0*
*Status: ACTIVE*