Building localized landing pages in Laravel: hreflang, pricing, and Product JSON-LD

Ricardo — Fri, 28 Aug 2026 03:47:27 +0000

International SEO looks simple until a product needs different language variants, currencies, payment providers, policies, and structured data for every market.

I ran into that problem while working on Invitav's digital invitation platform. It is a Laravel 12 application where hosts create mobile invitations with RSVP, maps, music, personal guest links, and an optional QR photo album.

The product was already useful, but its public pages had grown unevenly. A country page could show the correct local price while its metadata described something else. Some pages existed outside the sitemap. The Product schema was missing an image, and the commercial details in JSON-LD were less complete than the visible page.

This post explains the architecture we used to make those pieces consistent.

1. Treat each market as data, not as a copied template

The first rule was to avoid one Blade file per country. Copying a landing page 20 times makes the first launch fast and every later correction painful.

Instead, each market is a compact configuration record:

final class CountryLandingContent
{
    private static function countries(): array
    {
        return [
            'chile' => [
                'code' => 'CL',
                'name' => 'Chile',
                'lang' => 'es-CL',
                'currency' => 'CLP',
                'cities' => ['Santiago', 'Valparaíso', 'Concepción'],
                'celebrations' => ['matrimonios', 'cumpleaños', 'bautizos'],
            ],
            'mexico' => [
                'code' => 'MX',
                'name' => 'México',
                'lang' => 'es-MX',
                'currency' => 'MXN',
                'cities' => ['Ciudad de México', 'Guadalajara', 'Monterrey'],
                'celebrations' => ['bodas', 'XV años', 'cumpleaños'],
            ],
        ];
    }
}

One controller resolves the country, asks the pricing service for the applicable offers, and renders one view:

public function show(string $country, InvitationPricing $pricing): Response
{
    $page = CountryLandingContent::find($country);
    abort_unless($page, 404);

    $basic = $pricing->option($page['code'], InvitationPricing::TIER_BASIC);
    $premium = $pricing->option($page['code'], InvitationPricing::TIER_PREMIUM);

    return response()
        ->view('countries.show', compact('page', 'basic', 'premium'))
        ->header('Content-Language', $page['lang']);
}

This does more than reduce duplication. The same country code now drives:

the document language;
visible currency and price;
payment-provider copy;
canonical URL and alternates;
the country and currency in Product offers;
sitemap entries.

That single source of truth is the main protection against contradictory pages.

2. Generate a complete hreflang cluster

A localized page should not only identify itself. It should point to the other legitimate versions in the cluster.

We generate the alternates from the same market catalog:

public static function alternates(): array
{
    $alternates = collect(self::all())
        ->map(fn (array $country) => [
            'hreflang' => $country['lang'],
            'href' => 'https://example.com'.$country['url'],
        ])
        ->values()
        ->all();

    $alternates[] = [
        'hreflang' => 'en-US',
        'href' => 'https://example.com/us/digital-invitations',
    ];

    $alternates[] = [
        'hreflang' => 'x-default',
        'href' => 'https://example.com/digital-invitations-by-country',
    ];

    return $alternates;
}

The Blade template renders the canonical and every alternate:

<link rel="canonical" href="{{ $canonical }}">

@foreach ($alternates as $alternate)
    <link rel="alternate"
          hreflang="{{ $alternate['hreflang'] }}"
          href="{{ $alternate['href'] }}">
@endforeach

We also emit the same relationships in the XML sitemap. Keeping HTML and sitemap generation behind one service prevents them from drifting apart.

A subtle point: es-419 is useful for general Latin American Spanish, but a page clearly written and priced for Chile should use es-CL. Language annotations need to describe the actual page, not the audience we hope to attract.

3. Build Product JSON-LD from the commercial source of truth

The original Product markup had the basics: name, description, brand, and offers. Search Console still rejected the item because image was missing.

The immediate fix was small:

[
    '@type' => 'Product',
    '@id' => $canonical.'#product',
    'url' => $canonical,
    'name' => $productName,
    'description' => $description,
    'image' => [$productImage],
    'sku' => 'PRODUCT-'.$countryCode,
    'brand' => [
        '@type' => 'Brand',
        'name' => 'Invitav',
    ],
    'offers' => $offers,
]

But fixing only the critical field would leave warnings and, more importantly, incomplete commercial semantics. We moved offer generation to a reusable helper:

public static function digitalOffer(
    string $name,
    string $url,
    string $price,
    string $currency,
    string $countryCode,
): array {
    $zeroDays = [
        '@type' => 'QuantitativeValue',
        'minValue' => 0,
        'maxValue' => 0,
        'unitCode' => 'DAY',
    ];

    return [
        '@type' => 'Offer',
        'name' => $name,
        'url' => $url,
        'price' => $price,
        'priceCurrency' => $currency,
        'availability' => 'https://schema.org/InStock',
        'itemCondition' => 'https://schema.org/NewCondition',
        'shippingDetails' => [
            '@type' => 'OfferShippingDetails',
            'shippingRate' => [
                '@type' => 'MonetaryAmount',
                'value' => '0',
                'currency' => $currency,
            ],
            'shippingDestination' => [
                '@type' => 'DefinedRegion',
                'addressCountry' => $countryCode,
            ],
            'deliveryTime' => [
                '@type' => 'ShippingDeliveryTime',
                'handlingTime' => $zeroDays,
                'transitTime' => $zeroDays,
            ],
        ],
        'hasMerchantReturnPolicy' => [
            '@type' => 'MerchantReturnPolicy',
            'applicableCountry' => $countryCode,
            'returnPolicyCategory' =>
                'https://schema.org/MerchantReturnFiniteReturnWindow',
            'merchantReturnDays' => 30,
            'returnFees' => 'https://schema.org/FreeReturn',
        ],
    ];
}

For a digital product, “shipping” is really electronic fulfillment. We model it explicitly as free, zero-day delivery instead of implying a physical parcel.

There is an important boundary here: structured data must describe the real offer. It cannot be used to hide a contradiction between the checkout, refund page, and terms. We aligned the visible policy first, then encoded the same policy in JSON-LD.

4. Use one graph instead of unrelated schema fragments

Each country page now emits a single @graph containing:

WebPage, including language and geographic coverage;
BreadcrumbList;
Product, with localized offers;
FAQPage, matching questions visible on the page.

Stable @id values connect the nodes:

[
    '@context' => 'https://schema.org',
    '@graph' => [
        [
            '@type' => 'WebPage',
            '@id' => $canonical.'#webpage',
            'url' => $canonical,
            'mainEntity' => ['@id' => $canonical.'#product'],
        ],
        [
            '@type' => 'Product',
            '@id' => $canonical.'#product',
            // ...
        ],
    ],
]

This makes the relationship between the page and product explicit and avoids several disconnected objects that happen to share a URL.

5. Test the invariants, not every sentence

Localized content changes frequently. Tests that assert complete paragraphs become noisy, while tests that protect SEO invariants stay valuable.

These are the checks worth keeping:

it('renders a valid localized product graph', function () {
    $response = $this->get('/invitaciones-digitales-chile');

    $response->assertOk()
        ->assertSee('<html lang="es-CL"', false)
        ->assertSee('rel="canonical"', false)
        ->assertSee('hreflang="en-US"', false)
        ->assertSee('"@type":"Product"', false)
        ->assertSee('"image":[', false)
        ->assertSee('"priceCurrency":"CLP"', false)
        ->assertSee('"hasMerchantReturnPolicy"', false)
        ->assertSee('"shippingDetails"', false);
});

I also like running a small crawler against the public route list after deployment. It catches broken canonicals, accidental noindex, redirect chains, and 500s that unit tests cannot see in production.

What I would do differently next time

I would define the market catalog before creating the first localized page. Retrofitting shared rules is harder once prices, copy, metadata, and schema already come from different places.

The general lesson is straightforward: international SEO is a data consistency problem as much as a content problem. If language, market, pricing, policy, HTML metadata, sitemap, and JSON-LD all derive from the same small set of services, adding a country becomes predictable instead of risky.

If you are building localized landing pages in Laravel, I would start with three services: a market catalog, a pricing resolver, and a structured-data builder. The templates should mostly render decisions those services have already made.
``