LearnIT/docs/LANGUAGE_POLICY.md

🇵🇹 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:

// 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:

// 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