# Criazo Market Localization Architecture

## Active Markets

Only these markets are public:

- UK English: `/` (`en-GB`)
- US English: `/us` (`en-US`)
- Portugal Portuguese: `/pt` (`pt-PT`)
- Brazil Portuguese: `/br` (`pt-BR`)
- Spanish: `/es` (`es-ES`)
- French: `/fr` (`fr-FR`)

Other locale files may remain in the repository, but they must not appear in public routing, navigation, language switching, hreflang, or sitemaps until a full market content rollout is complete.

## URL Rules

- UK has no prefix.
- US, PT, BR, ES, and FR keep their exact public prefixes.
- Do not rename `/br` to `/pt-BR`.
- Do not translate service slugs, route keys, project IDs, or industry IDs unless the routing layer explicitly supports that change.
- Internal links should use market-aware URL helpers so users stay inside the current market.

## Content Structure

Public market copy lives in:

- `content/uk/`
- `content/us/`
- `content/pt/`
- `content/br/`
- `content/es/`
- `content/fr/`

Current market-owned content files include:

- `services.php`
- `home.php`
- `contact.php`
- `portfolio.php`
- `industries.php`
- `about.php`
- `legal.php`

Shared Blade components, layouts, and backend logic are allowed. Market-facing copy, SEO metadata, CTAs, FAQs, cards, testimonials, labels, alt text, and aria labels must come from the selected market content source.

## MarketContent

Use `App\Helpers\MarketContent` for public market content. It loads the exact content file for the active market and validates required keys.

For PT, BR, ES, and FR, missing public content must fail loudly in local/testing instead of silently falling back to English. Laravel's global fallback may remain available for backend/admin copy, but public pages should not depend on it.

## SEO

- Canonicals must point to the current market URL.
- Hreflang must include only the six active markets.
- `x-default` points to `/`.
- Sitemaps must include only active markets.
- Disabled locales must not appear in public SEO output.

## Language Switcher

The language switcher should generate equivalent-market URLs from the current request path when available:

- `/local-seo` -> `/pt/local-seo`
- `/pt/local-seo` -> `/br/local-seo`
- `/br/contact` -> `/fr/contact`
- `/fr/about` -> `/about`

If the equivalent route is unavailable, fall back to that market homepage.

## Approved English Exceptions

Allowed English or unchanged tokens include brand names, product/platform names, acronyms, URLs, variables, and technical identifiers, for example:

- Criazo
- Google Ads
- Meta Ads
- TikTok Ads
- WordPress
- Shopify
- WooCommerce
- SEO
- CRM
- CRO
- ROAS
- URLs, email addresses, internal IDs, route slugs

## Validation Commands

Run before deployment:

```bash
php artisan optimize:clear
php scripts/validate-localization.php
php artisan criazo:validate-rendered-localization http://127.0.0.1:8123 sitemap
php artisan route:list
```

The rendered validator checks public HTML, metadata, nav, footer, CTAs, cards, FAQs, testimonials, portfolio sections, forms, buttons, legal links, aria labels, alt text, placeholders, canonical, hreflang, sitemap exposure, disabled locale leakage, and market-preserving internal links.

## Adding a Future Locale

1. Keep the locale disabled publicly.
2. Create a market folder under `content/{market}/`.
3. Add every required content file with complete copy.
4. Keep IDs and slugs stable.
5. Add the market to `config/markets.php`.
6. Add language switcher, hreflang, sitemap, and validation expectations.
7. Run both localization validators and route probes.
8. Review rendered pages manually with a native speaker before public release.

## Common Mistakes

- Adding English fallback copy to PT, BR, ES, or FR pages.
- Translating route slugs or array keys.
- Hardcoding public copy in Blade when a market content file exists.
- Adding a locale to navigation before its content is complete.
- Generating hreflang or sitemap URLs for disabled locales.
- Using UK copy as US copy without reviewing spelling and market wording.
- Treating Portugal Portuguese and Brazil Portuguese as interchangeable.
- Assuming legal translations are approved without human legal review.