goodgo-platform/FILE_MAPPING_GUIDE.md

GoodGo Frontend: File-by-File i18n & A11y Implementation Guide

📋 Complete File Mapping

PHASE 1: INFRASTRUCTURE SETUP

1. middleware.ts (CRITICAL)

Current: Auth routing only
Changes:

• Add locale detection from URL pathname
• Add cookie-based locale storage
• Redirect /en/* and /vi/* paths appropriately
• Add Accept-Language header fallback

Pseudo-code:

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  
  // Extract locale from URL: /en/*, /vi/*, or default
  const locale = extractLocale(pathname) || getPreferredLocale(request);
  
  // ... existing auth logic ...
  
  // If no locale prefix, add it
  if (!locale) {
    return NextResponse.redirect(new URL(`/${locale}${pathname}`, request.url));
  }
  
  // Set locale cookie for client-side
  response.cookies.set('goodgo_locale', locale);
}

2. app/layout.tsx (CRITICAL)

Current: Thai providers, hardcoded Vietnamese metadata
Changes:

• Change lang="vi" to dynamic locale
• Update metadata to be i18n-aware
• Wrap with NextIntlClientProvider from next-intl
• Keep existing providers (ThemeProvider, QueryProvider, AuthProvider)

Key changes:

import { getLocale, getTranslations } from 'next-intl/server';

export async function generateMetadata(): Promise<Metadata> {
  const locale = getLocale();
  const t = getTranslations();
  
  return {
    title: t('common.site_name'),
    description: t('common.site_description'),
    openGraph: {
      locale: locale === 'en' ? 'en_US' : 'vi_VN',
      ...
    }
  };
}

3. i18n/config.ts (NEW)

Create new file with i18n configuration:

export const locales = ['en', 'vi'] as const;
export const defaultLocale = 'vi';

export const timeZone = 'Asia/Ho_Chi_Minh';

4. public/locales/en.json (NEW - LARGE FILE)

Structure:

{
  "common": {
    "site_name": "GoodGo",
    "site_description": "Smart real estate platform in Vietnam",
    "home": "Home",
    "search": "Search",
    "dashboard": "Dashboard",
    "logout": "Logout",
    "loading": "Loading...",
    "error": "An error occurred",
    "try_again": "Try again"
  },
  "auth": {
    "login": "Login",
    "register": "Register",
    "phone": "Phone number",
    "password": "Password",
    "confirm_password": "Confirm password",
    "no_account": "Don't have an account?",
    "sign_up": "Sign up",
    "sign_in": "Sign in",
    "oauth_failed": "Social login failed. Please try again.",
    "access_denied": "You denied access. Please try again.",
    "invalid_request": "Invalid login request. Please try again.",
    "server_error": "Server error. Please try again later.",
    "show_password": "Show",
    "hide_password": "Hide"
  },
  "property": {
    "apartment": "Apartment",
    "house": "House",
    "villa": "Villa",
    "land": "Land",
    "office": "Office",
    "shophouse": "Shophouse",
    "price": "Price",
    "area": "Area",
    "bedrooms": "Bedrooms",
    "bathrooms": "Bathrooms",
    "direction": "Direction"
  },
  "transaction": {
    "sale": "Sale",
    "rent": "Rent",
    "buy": "Buy",
    "lease": "Lease"
  },
  "direction": {
    "north": "North",
    "south": "South",
    "east": "East",
    "west": "West",
    "northeast": "Northeast",
    "northwest": "Northwest",
    "southeast": "Southeast",
    "southwest": "Southwest"
  },
  "status": {
    "draft": "Draft",
    "pending_review": "Pending review",
    "active": "Active",
    "reserved": "Reserved",
    "sold": "Sold",
    "rented": "Rented",
    "expired": "Expired",
    "rejected": "Rejected"
  },
  "validation": {
    "required": "This field is required",
    "min_length": "Minimum {count} characters",
    "invalid_phone": "Invalid phone number",
    "invalid_email": "Invalid email",
    "passwords_match": "Passwords must match"
  },
  "navigation": {
    "home": "Home",
    "search": "Search",
    "create_listing": "Create listing",
    "my_listings": "My listings",
    "analytics": "Analytics",
    "valuation": "Valuation",
    "profile": "Profile",
    "subscription": "Subscription",
    "payments": "Payments",
    "admin_dashboard": "Admin",
    "admin_users": "Users",
    "admin_kyc": "KYC",
    "admin_moderation": "Moderation"
  },
  "landing": {
    "hero_title": "Find your perfect real estate",
    "hero_subtitle": "Smart real estate platform in Vietnam",
    "search_placeholder": "Enter area, project, or keyword...",
    "featured_listings": "Featured listings",
    "districts": "Popular districts",
    "stats_title": "GoodGo in numbers",
    "stats_listings": "Listings",
    "stats_users": "Users",
    "stats_transactions": "Successful transactions",
    "stats_cities": "Cities",
    "cta_title": "Have a property to list?",
    "cta_subtitle": "List for free today, reach thousands of potential buyers",
    "cta_register": "Sign up free",
    "cta_search": "Search now"
  }
}

5. public/locales/vi.json (NEW - LARGE FILE)

Same structure as en.json but with Vietnamese translations.

---

PHASE 2: CORE COMPONENT UPDATES

Files Requiring Translation Hook Integration

Layout Files

1. app/(public)/layout.tsx

// Current: Hardcoded nav items
const navItems = [
  { href: '/', label: 'Trang chủ' },
  { href: '/search', label: 'Tìm kiếm' },
];

// After i18n:
export default function PublicLayout() {
  const t = useTranslations('navigation');
  const navItems = [
    { href: '/', label: t('home') },
    { href: '/search', label: t('search') },
  ];
  
  // Also update footer content
}

2. app/(dashboard)/layout.tsx

// Update all 8 nav items to use t('navigation.item_name')
// Update theme toggle aria-label
const toggleLabel = theme === 'light' 
  ? t('common.toggle_dark_mode') 
  : t('common.toggle_light_mode');

3. app/(auth)/layout.tsx Update any error messages or labels to use translations.

Page Files

1. app/(public)/page.tsx (LARGE FILE) Areas to update:

• Hero section (title, subtitle)
• Search form (placeholder)
• Property type badges
• Price ranges
• City options
• Section headings
• Stats labels
• CTA buttons

export default function LandingPage() {
  const t = useTranslations();
  
  const PROPERTY_TYPES_LABELS = PROPERTY_TYPES.map(pt => ({
    value: pt.value,
    label: t(`property.${pt.value.toLowerCase()}`),
  }));
  
  // Update all hardcoded strings:
  // Hero title: t('landing.hero_title')
  // Hero subtitle: t('landing.hero_subtitle')
  // Search placeholder: t('landing.search_placeholder')
  // etc.
}

2. app/(auth)/login/page.tsx

// Update all form labels to use t()
const phoneLabel = t('auth.phone');
const passwordLabel = t('auth.password');
const loginButton = t('auth.sign_in');

// OAuth error messages - move to translations
const OAUTH_ERROR_MESSAGES = {
  oauth_failed: t('auth.oauth_failed'),
  access_denied: t('auth.access_denied'),
  // ... etc
};

3. app/(auth)/register/page.tsx Same pattern as login page.

4. app/(dashboard)/dashboard/page.tsx and all other dashboard pages Update section titles, empty states, button labels.

Search & Listing Pages

1. app/(public)/search/page.tsx Update search results headings, empty states, filter labels.

2. app/(public)/listings/[id]/page.tsx Update property detail labels.

3. app/(dashboard)/listings/page.tsx Update table headers, status labels, action labels.

4. app/(dashboard)/listings/new/page.tsx Uses listing-form-steps component (see below).

---

Component Files

Critical Components (Do First)

1. components/search/filter-bar.tsx (HIGH PRIORITY)

// Current: Hardcoded arrays
const CITIES = ['Hồ Chí Minh', 'Hà Nội', 'Đà Nẵng', ...];
const PRICE_RANGES = [
  { label: 'Dưới 1 tỷ', ... },
  { label: '1 - 3 tỷ', ... },
];

// After i18n:
const CITIES = t('locations.cities').split(',');
const PRICE_RANGES = [
  { label: t('search.price_under_1b'), ... },
  { label: t('search.price_1_3b'), ... },
];

2. components/listings/listing-form-steps.tsx (HIGH PRIORITY - LARGE FILE) This multi-step form has many labels to translate:

• Step 1: Transaction type, property type, title, description
• Step 2: Address fields, location
• Step 3: Area, rooms, bathrooms, direction, year built, etc.
• Step 4: Pricing

All field labels should use t('form.field_name') pattern.

3. components/auth/oauth-buttons.tsx

// Update button text
<Button>
  {t('auth.google')}  // Currently hardcoded "Google"
</Button>
<Button>
  {t('auth.zalo')}    // Currently hardcoded "Zalo"
</Button>

Medium Priority Components

1. components/search/property-card.tsx

// Update PROPERTY_TYPE_LABELS to use translations
const t = useTranslations();
const PROPERTY_TYPE_LABELS = {
  APARTMENT: t('property.apartment'),
  HOUSE: t('property.house'),
  // ... etc
};

// Update aria-labels to use translations
aria-label={t('property.card_label', { 
  title: listing.property.title,
  type: propertyTypeLabel,
  price: formatPrice(listing.priceVND)
})}

2. components/listings/listing-status-badge.tsx

// Update status labels
const LISTING_STATUSES = {
  DRAFT: { label: t('status.draft'), variant: 'secondary' },
  ACTIVE: { label: t('status.active'), variant: 'success' },
  // ... etc
};

3. components/valuation/valuation-form.tsx Update form labels and buttons.

4. components/listings/image-upload.tsx Update button text and error messages.

5. All components/ui/*.tsx files with text

• Button: any default text
• Dialog: Close button aria-label
• Input: placeholder attrs if hardcoded
• Label: any default text
• Others: similar

---

PHASE 3: VALIDATION & ERROR MESSAGES

1. lib/validations/auth.ts

// Current:
const loginSchema = z.object({
  phone: z.string().min(1, 'Vui lòng nhập số điện thoại'),
  password: z.string().min(1, 'Vui lòng nhập mật khẩu'),
});

// After i18n - move to message files and use in component:
// In component:
const t = useTranslations('validation');
const schema = z.object({
  phone: z.string().min(1, t('required')),
  password: z.string().min(1, t('required')),
});

2. lib/validations/listings.ts (LARGE FILE)

Update all Zod validation error messages:

• "Vui lòng chọn loại giao dịch" → t('validation.transaction_required')
• "Tiêu đề tối thiểu 5 ký tự" → t('validation.title_min_length')
• All other validation messages

3. lib/validations/valuation.ts

Similar pattern to listings.

---

PHASE 4: UTILITY UPDATES

1. lib/utils.ts

No changes (already minimal).

2. lib/auth-store.ts

// Check if any error messages are hardcoded
// If so, move to i18n and pass locale context

3. lib/api-client.ts

Check if error messages from API need i18n wrapping.

4. All lib/*-api.ts files

Update error message handling if needed.

---

PHASE 5: ACCESSIBILITY UPDATES

1. components/ui/dialog.tsx (CRITICAL A11y)

Add focus management:

// Add focus trap
// Save initial focus element
// On mount: move focus to dialog
// On close: restore focus to initial element
// On Escape key: close dialog

import { useEffect, useRef } from 'react';

function Dialog() {
  const initialFocusRef = useRef<HTMLElement>(null);
  
  useEffect(() => {
    // Set initial focus
    const firstButton = dialogRef.current?.querySelector('button');
    firstButton?.focus();
    
    // Trap focus
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Tab') {
        // Prevent focus from leaving dialog
      }
      if (e.key === 'Escape') {
        onClose?.();
      }
    };
    
    document.addEventListener('keydown', handleKeyDown);
    return () => {
      document.removeEventListener('keydown', handleKeyDown);
      // Restore focus
      (initialFocusRef.current as HTMLElement | null)?.focus();
    };
  }, []);
}

2. components/ui/input.tsx

Add aria-describedby for error messages:

export function Input({ error, ...props }) {
  const errorId = `${props.id}-error`;
  return (
    <>
      <input
        {...props}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && <p id={errorId} role="alert">{error}</p>}
    </>
  );
}

3. components/ui/button.tsx

Ensure all buttons have visible focus indicator (already in CSS likely). Add aria-busy for loading state if used:

export function Button({ disabled, isLoading, ...props }) {
  return (
    <button
      {...props}
      disabled={disabled || isLoading}
      aria-busy={isLoading}
    >
      {/* content */}
    </button>
  );
}

4. Form Components

Update all forms to use aria-describedby for error messages:

• app/(auth)/login/page.tsx — Already has role="alert" ✓ but could use aria-describedby
• app/(auth)/register/page.tsx — Same
• components/listings/listing-form-steps.tsx — Add aria-describedby
• components/search/filter-bar.tsx — Ensure accessible labels

5. All Icon-Only Buttons

Find all buttons with only icons and add aria-label:

// Search in components for: <Button> with only SVG children
// Add aria-label={t('...')}

// Examples:
<Button aria-label={t('common.close')}>
  <X />
</Button>

<Button aria-label={t('common.toggle_dark_mode')}>
  <Moon />
</Button>

6. Loading Spinners

Add aria-busy and aria-label:

// In app/(public)/page.tsx and similar:
<div aria-busy={loadingFeatured} aria-label={t('common.loading')}>
  <div className="h-8 w-8 animate-spin rounded-full..." />
</div>

7. components/listings/image-gallery.tsx

Add keyboard navigation (arrow keys):

// Add keyboard event handler for arrow keys
// Left/Right arrows to navigate images

---

PHASE 6: TEST SETUP UPDATES

1. vitest.setup.ts

// Mock next-intl for tests
vi.mock('next-intl', () => ({
  useTranslations: () => (key) => key, // Return key as-is for testing
  getTranslations: async () => (key) => key,
}));

// Or provide full mock messages
const mockMessages = {
  common: { home: 'Home', search: 'Search' },
  auth: { login: 'Login', register: 'Register' },
  // ... etc
};

vi.mock('next-intl', () => ({
  useTranslations: (namespace) => (key) => mockMessages[namespace]?.[key] || key,
}));

2. vitest.config.ts

May need to add path aliases or test environment setup.

3. Update all test files in __tests__/ folders

• Add locale prop to component renders
• Test both English and Vietnamese if applicable
• Mock i18n translations

---

📊 Summary: Files by Update Complexity

Trivial (5 min each)

• app/robots.ts
• app/sitemap.ts
• components/ui/badge.tsx
• components/ui/card.tsx
• components/ui/tabs.tsx

Simple (15-30 min each)

• app/(admin)/*.tsx files (3 files)
• app/(dashboard)/analytics/page.tsx
• app/(dashboard)/profile/page.tsx
• app/(dashboard)/subscription/page.tsx
• app/(dashboard)/payments/page.tsx
• components/ui/*.tsx (8 files)
• components/auth/oauth-buttons.tsx
• components/listings/listing-status-badge.tsx

Medium (30-60 min each)

• app/(public)/layout.tsx
• app/(auth)/login/page.tsx
• app/(auth)/register/page.tsx
• app/(dashboard)/layout.tsx
• app/(dashboard)/dashboard/page.tsx
• app/(public)/search/page.tsx
• components/search/property-card.tsx
• components/search/filter-bar.tsx
• components/listings/image-upload.tsx
• components/valuation/*.tsx (3 files)

Complex (1-2 hours each)

• app/(public)/page.tsx (landing page - many sections)
• components/listings/listing-form-steps.tsx (multi-step form)
• components/map/listing-map.tsx (if has labels)
• components/charts/*.tsx (3 files - chart labels)

Critical Infrastructure

• middleware.ts (30-45 min)
• app/layout.tsx (30 min)
• lib/validations/*.ts (3 files - 45 min)

---

✅ Validation Checklist

Before considering i18n + A11y complete:

i18n Verification

• Both /en/* and /vi/* routes work
• All text from messages files, not hardcoded
• Metadata changes with locale
• Cookies/headers work for locale selection
• Validation messages use i18n
• All enums use translations
• Tests mock i18n correctly

A11y Verification

• Focus trap works in dialogs
• Focus indicator visible on all inputs
• Form errors linked with aria-describedby
• Icon buttons all have aria-labels
• Color contrast >= 4.5:1 for text (AA standard)
• Keyboard navigation works everywhere
• Screen reader testing (NVDA/JAWS)
• Loading spinners have aria-busy
• All tables have proper headers

---

Generated: April 9, 2026
Confidence: High
Total Estimated Files to Update: 50-60 files