230 lines
6.1 KiB
Markdown
230 lines
6.1 KiB
Markdown
# 🇵🇹 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*
|