@faststore/core 4.5.0-dev.2 → 4.5.0-dev.4

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.5.0-dev.4](https://github.com/vtex/faststore/compare/v4.5.0-dev.3...v4.5.0-dev.4) (2026-07-24)
+
+### Features
+
+- **core:** localized product URLs, breadcrumbs PDP and PLPs ([#3402](https://github.com/vtex/faststore/issues/3402)) ([3c6b6ef](https://github.com/vtex/faststore/commit/3c6b6ef29ef902ccae3ff784297b24e6c6bc7802)), closes [#3352](https://github.com/vtex/faststore/issues/3352) [#3401](https://github.com/vtex/faststore/issues/3401)
+
+# [4.5.0-dev.3](https://github.com/vtex/faststore/compare/v4.5.0-dev.2...v4.5.0-dev.3) (2026-07-22)
+
+### Features
+
+- **core:** move recommendation session start to CMS Global Section ([8589056](https://github.com/vtex/faststore/commit/8589056046b38e5dbc4f8ce6dcc669f7a15a4d85))
+
 # [4.5.0-dev.2](https://github.com/vtex/faststore/compare/v4.5.0-dev.1...v4.5.0-dev.2) (2026-07-20)
 
 **Note:** Version bump only for package @faststore/core

package/cms/faststore/components/cms_component__recommendationshelf.jsonc

@@ -3,10 +3,16 @@
   "$componentKey": "RecommendationShelf",
   "$componentTitle": "Recommendation Shelf",
   "title": "Recommendation Shelf",
-  "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign.",
+  "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign. Enable the shelf with the Enable recommendations toggle (off by default).",
   "type": "object",
   "required": ["campaignVrn"],
   "properties": {
+    "enableRecommendations": {
+      "title": "Enable recommendations?",
+      "description": "When enabled, starts the VTEX Recommendations personalization session (once per browser session) and fetches personalized products for this shelf. Off by default so stores that do not use Recommendations never hit the Recommendations API.",
+      "type": "boolean",
+      "default": false
+    },
     "title": {
       "title": "Title",
       "description": "Override the shelf title. If not set, the campaign title will be used.",

package/cms/faststore/schema.json

@@ -4434,10 +4434,16 @@
       "$componentKey": "RecommendationShelf",
       "$componentTitle": "Recommendation Shelf",
       "title": "Recommendation Shelf",
-      "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign.",
+      "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign. Enable the shelf with the Enable recommendations toggle (off by default).",
       "type": "object",
       "required": ["campaignVrn"],
       "properties": {
+        "enableRecommendations": {
+          "title": "Enable recommendations?",
+          "description": "When enabled, starts the VTEX Recommendations personalization session (once per browser session) and fetches personalized products for this shelf. Off by default so stores that do not use Recommendations never hit the Recommendations API.",
+          "type": "boolean",
+          "default": false
+        },
         "title": {
           "title": "Title",
           "description": "Override the shelf title. If not set, the campaign title will be used.",

package/discovery.config.default.js

@@ -201,9 +201,6 @@ module.exports = {
     },
     refreshToken: false,
     scrollRestoration: false,
-    // Opt-in flag for VTEX Recommendations. When disabled (default), the store
-    // never starts a personalization session nor calls the Recommendations API.
-    enableRecommendations: false,
     /** Package names to transpile (e.g. ['@vtex/components']). Use a non-empty list to enable Next.js transpilation. */
     transpilePackages: [],
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.5.0-dev.2",
+  "version": "4.5.0-dev.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/api": "4.5.0-dev.2",
-    "@faststore/lighthouse": "4.5.0-dev.2",
-    "@faststore/diagnostics": "4.5.0-dev.2",
-    "@faststore/sdk": "4.5.0-dev.2",
-    "@faststore/ui": "4.5.0-dev.2"
+    "@faststore/lighthouse": "4.5.0-dev.4",
+    "@faststore/api": "4.5.0-dev.4",
+    "@faststore/sdk": "4.5.0-dev.4",
+    "@faststore/ui": "4.5.0-dev.4",
+    "@faststore/diagnostics": "4.5.0-dev.4"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/Layout.tsx

@@ -6,11 +6,10 @@ import { useStartRecommendationSession } from './sdk/analytics/hooks/useStartRec
 function Layout({ children }: PropsWithChildren) {
   const props = isValidElement(children) ? children.props : undefined
   usePageViewEvent(props)
-  // Implemented here because the personalization session must be initiated once
-  // per browser session on each page. Gated behind the
-  // `experimental.enableRecommendations` flag: stores that don't opt into
-  // Recommendations never start a session nor call the Recommendations API.
-  useStartRecommendationSession()
+
+  // Starts the personalization session once per browser session when the page
+  // CMS data includes a RecommendationShelf with `enableRecommendations: true`.
+  useStartRecommendationSession(props)
 
   return <>{children}</>
 }

package/src/components/sections/EmptyState/EmptyState.tsx

@@ -1,5 +1,5 @@
-import type { PropsWithChildren } from 'react'
 import { useRouter } from 'next/router'
+import type { PropsWithChildren } from 'react'
 
 import { Icon as UIIcon, Loader as UILoader } from '@faststore/ui'
 
@@ -9,8 +9,8 @@ import Section from '../Section'
 
 import styles from './section.module.scss'
 
-import { EmptyStateDefaultComponents } from './DefaultComponents'
 import { getOverridableSection } from '../../../sdk/overrides/getOverriddenSection'
+import { EmptyStateDefaultComponents } from './DefaultComponents'
 
 export interface EmptyStateProps {
   /**
@@ -53,11 +53,12 @@ const useErrorState = () => {
     query: { errorId, fromUrl },
     pathname,
     asPath,
+    locale,
   } = router
 
   return {
     errorId,
-    fromUrl: fromUrl ?? asPath ?? pathname,
+    fromUrl: fromUrl ?? (locale ? `/${locale}${asPath}` : asPath) ?? pathname,
   }
 }
 

package/src/components/sections/RecommendationShelf/README.md

@@ -0,0 +1,163 @@
+# Recommendation Shelf
+
+CMS section that renders a carousel of personalized product recommendations from a **VTEX Recommendations** campaign. It uses the same product cards (`ProductCard`) as other store shelves; items come from a recommendation campaign (cross-sell, similar items, top sellers, personalized, and related types) instead of a search query.
+
+- **Data source:** VTEX Recommendations BFF, exposed by `@faststore/api` through the `recommendations` GraphQL query.
+- **Registration:** global CMS component (`$componentKey: "RecommendationShelf"`), available on any page via CMS.
+- **Opt-in via CMS:** enable Recommendations with the **Enable recommendations?** toggle on the shelf (default `false`). No store code changes or feature flags are required.
+
+## Contents
+
+- [Prerequisites](#prerequisites)
+- [Setup](#setup)
+- [CMS configuration](#cms-configuration)
+- [Campaign types (VRN) and context](#campaign-types-vrn-and-context)
+- [Runtime behavior](#runtime-behavior)
+- [Code-level overrides](#code-level-overrides)
+- [Placement guidelines](#placement-guidelines)
+- [Privacy and cache](#privacy-and-cache)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+The shelf renders products only when the following conditions are met:
+
+1. **Enable recommendations on the shelf.** Set **Enable recommendations?** to `true` on the Recommendation Shelf in the CMS. This opts the store into the personalization session (`startRecommendationSession` mutation, owned by Layout) and allows the shelf to fetch recommendations. Without it (default `false`), no session is started and the shelf does not fetch.
+
+2. **Active VTEX Recommendations campaign.** Provide a valid campaign **VRN**. Example: `vrn:recommendations:my-account:rec-persona-v2:abc123`.
+
+3. **Activity Flow script (optional, recommended).** Used for analytics:
+   - reads PDP `product:*` meta tags to capture product view events;
+   - reads `data-af-*` attributes on the shelf to capture impression, view, and click events.
+
+## Setup
+
+### 1. Obtain the campaign VRN
+
+In the VTEX Recommendations admin, create or select a campaign and copy its **VRN**. The expected format is:
+
+```text
+vrn:recommendations:<account>:<campaign-type>:<campaign-id>
+```
+
+Supported `<campaign-type>` values are listed under [Campaign types (VRN) and context](#campaign-types-vrn-and-context).
+
+### 2. Add Recommendation Shelf via CMS
+
+Add **Recommendation Shelf** to the target page (home, PDP, PLP, cart, and so on), configure at least **Campaign VRN** (required), and turn **Enable recommendations?** on.
+
+## CMS configuration
+
+Schema: `cms/faststore/components/cms_component__recommendationshelf.jsonc`.
+
+| CMS property | Key | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| Enable recommendations? | `enableRecommendations` | boolean | No | `false` | Opt-in that starts the personalization session (via Layout) and allows this shelf to fetch recommendations. |
+| Title | `title` | string | No | — | Overrides the shelf title. Falls back to the campaign title. If both are empty, the heading is not rendered. |
+| Campaign VRN | `campaignVrn` | string | **Yes** | — | Recommendation campaign VRN. Validated by regex (see campaign types below). |
+| Items context | `itemsContext` | `PDP` \| `CART` | No | `PDP` | Source of products used as request context. Applies only to context-based campaigns. |
+| **Carousel Configuration** | `carouselConfiguration` | object | No | — | Carousel settings. |
+| › Items per page (desktop) | `itemsPerPageDesktop` | number | No | `4` | Items per page on desktop. |
+| › Items per page (mobile) | `itemsPerPageMobile` | number | No | `2` | Items per page on mobile and tablet (≤ 768px). |
+| › Carousel track variant | `variant` | `slide` \| `scroll` | No | `scroll` | Carousel navigation mode. |
+| › Infinite navigation? | `infiniteMode` | boolean | No | `false` | Infinite navigation (slide variant only). |
+| › Navigation controls | `controls` | `complete` \| `navigationArrows` \| `paginationBullets` | No | `complete` | Visible navigation controls. |
+| **Product Card Configuration** | `productCardConfiguration` | object | No | — | Product card settings. |
+| › Show discount badge? | `showDiscountBadge` | boolean | No | `true` | Shows the discount badge. |
+| › Cards should be bordered? | `bordered` | boolean | No | `true` | Renders bordered cards. |
+
+## Campaign types (VRN) and context
+
+The campaign type is derived from the `<campaign-type>` segment of the VRN:
+
+| Campaign | VRN segment | Internal type | Requires product context? |
+| --- | --- | --- | --- |
+| Cross-Sell | `rec-cross-v2` | `CROSS_SELL` | **Yes** |
+| Similar Items | `rec-similar-v2` | `SIMILAR_ITEMS` | **Yes** |
+| Visual Similarity | `rec-visual-v2` | `VISUAL_SIMILARITY` | **Yes** |
+| Next Interactions | `rec-next-v2` | `NEXT_INTERACTION` | **Yes** |
+| Personalized | `rec-persona-v2` | `PERSONALIZED` | No |
+| Top Sellers | `rec-top-items-v2` | `TOP_ITEMS` | No |
+| Last Seen | `rec-last-v2` | `LAST_SEEN` | No |
+| Search-Based | `rec-search-v2` | `SEARCH_BASED` | No |
+
+**Product context (`itemsContext`):**
+
+- `PDP` (default): uses the current product detail page product (`productGroupID`). Outside a PDP there is no product context.
+- `CART`: uses the products currently in the cart (deduplicated). Intended for cross-sell on the cart page.
+
+Context-based campaigns (cross-sell, similar items, visual similarity, next interaction) skip the request when no context products are available. Context-agnostic campaigns (top sellers, personalized, last seen, search-based) ignore `itemsContext`.
+
+## Runtime behavior
+
+All recommendation work runs client-side after hydration:
+
+1. **Session start (CMS opt-in)** — `Layout` calls `useStartRecommendationSession(pageProps)` once. The hook checks whether any `RecommendationShelf` in the CMS data has `enableRecommendations: true` and no-ops when none do. Multiple enabled shelves on the same page still start the session only once (in-memory lock + session cookie).
+2. **User id resolution** — `useRecommendationUserId()` reads the `vtex-rec-user-id` cookie, retrying until a value is available or the retry budget is exhausted.
+3. **Request arguments** — when enabled, `getRecommendationArguments()` builds `{ userId, campaignVrn, products }` or returns `null` when the VRN is invalid, the user id is missing, or a context-based campaign has no context products. When disabled, arguments stay `null`.
+4. **Fetch** — `useRecommendations()` runs `ClientRecommendationsQuery` and returns `products`, `correlationId`, and `campaign`.
+5. **Render** — shows `ProductShelfSkeleton` while loading; returns `null` on error or empty results; otherwise renders the carousel and optional heading.
+6. **Tracking** — when correlation and campaign identifiers are present, the shelf emits `data-af-*` attributes for Activity Flow. PDP product views use `product:*` meta tags from `pages/[slug]/p.tsx`.
+
+Related files:
+
+- Shelf: `src/components/sections/RecommendationShelf/`
+- Hook: `src/sdk/analytics/hooks/useStartRecommendationSession.ts`
+- Layout: `src/Layout.tsx`
+
+## Code-level overrides
+
+In addition to CMS props, the component accepts code-level overrides (not exposed in the CMS schema):
+
+```tsx
+import { RecommendationShelf } from 'src/components/sections/RecommendationShelf'
+
+<RecommendationShelf
+  enableRecommendations
+  campaignVrn="vrn:recommendations:my-account:rec-cross-v2:abc123"
+  itemsContext="PDP"
+  ProductCard={MyCustomCard}
+  mapProductToProductCard={(product, index) => ({
+    product,
+    index,
+    highlight: index === 0,
+  })}
+  carouselConfiguration={{ itemsPerPageDesktop: 5, variant: 'slide' }}
+/>
+```
+
+- **`ProductCard`**: custom card component (defaults to the core `ProductCard`).
+- **`mapProductToProductCard`**: maps each recommended product (normalized `StoreProduct`) into card props. When provided, it fully owns the card props and the default `productCardConfiguration` merge no longer applies.
+
+Campaign types and VRN validation are defined in `vrn.ts` (`VRN_TYPE_TO_RECOMMENDATION`). Updates should be made there and mirrored in the CMS schema `pattern`.
+
+## Placement guidelines
+
+As a global component, the shelf can be placed on any CMS page. Suggested placements by campaign type:
+
+- **Home / institutional pages:** context-agnostic campaigns (top sellers, personalized, last seen, search-based).
+- **PDP:** context-based campaigns with `itemsContext: PDP`.
+- **Cart:** cross-sell with `itemsContext: CART`.
+- **PLP:** context-agnostic campaigns.
+
+The personalization session runs only when at least one shelf has **Enable recommendations?** turned on.
+
+## Privacy and cache
+
+- The `recommendations` query uses `@cacheControl(scope: "private", sMaxAge: 120, staleWhileRevalidate: 3600)`.
+- Error logs omit `recommendationArgs` (which includes `userId`) and log only non-identifying context such as `campaignVrn`.
+- BFF `vtex-rec-*` cookies are forwarded to the browser through `ctx.storage.cookies`.
+
+## Troubleshooting
+
+**The shelf does not render.** Check, in order:
+
+1. Is **Enable recommendations?** set to `true` on the shelf?
+2. Is `campaignVrn` valid and is the campaign active?
+3. Is the `vtex-rec-user-id` cookie available? Without a user id, the shelf does not fetch.
+4. For context-based campaigns, is product context available (`PDP` on a product page, or a non-empty cart for `CART`)?
+5. Did the campaign return products? An empty response renders nothing by design.
+
+**Skeleton never resolves.** Inspect the console and the GraphQL `recommendations` response for pending or failing requests.
+
+**No tracking events.** Confirm that the Activity Flow script is present and that PDP `product:*` meta tags and shelf `data-af-*` attributes are rendered.

package/src/components/sections/RecommendationShelf/RecommendationShelf.tsx

@@ -4,8 +4,6 @@ import { usePDP } from '@faststore/core'
 import { ProductShelf, Carousel } from '@faststore/ui'
 import type { ProductSummary_ProductFragment } from '@generated/graphql'
 
-import storeConfig from 'discovery.config'
-
 import DefaultProductCard, {
   type ProductCardProps,
 } from 'src/components/product/ProductCard'
@@ -66,6 +64,7 @@ export function RecommendationShelf<
 >({
   title,
   campaignVrn,
+  enableRecommendations = false,
   itemsContext = 'PDP',
   ProductCard,
   mapProductToProductCard,
@@ -120,9 +119,9 @@ export function RecommendationShelf<
     return pdpProduct ? [pdpProduct] : []
   }, [itemsContext, cartItems, productDetailPage])
 
-  // Gate the whole feature behind the opt-in flag: when Recommendations is
+  // Gate the whole feature behind the CMS opt-in: when Recommendations is
   // disabled the shelf never requests recommendations (nor renders).
-  const recommendationArgs = storeConfig.experimental.enableRecommendations
+  const recommendationArgs = enableRecommendations
     ? getRecommendationArguments(campaignVrn, {
         userId,
         contextProducts,

package/src/components/sections/RecommendationShelf/RecommendationShelf.types.ts

@@ -30,6 +30,13 @@ export type RecommendationShelfProps<
 > = {
   readonly title?: string
   readonly campaignVrn: string
+  /**
+   * Opt-in for VTEX Recommendations on this shelf. When `true`, Layout starts
+   * the personalization session (`useStartRecommendationSession`) and this
+   * shelf fetches recommendations. When `false` (default), neither happens.
+   * @default false
+   */
+  readonly enableRecommendations?: boolean
   /**
    * Where to read the products used as context for the recommendation request:
    * - `'PDP'`: the current product detail page product.
@@ -45,7 +52,7 @@ export type RecommendationShelfProps<
   /**
    * Custom card component rendered for each recommended product. Defaults to the
    * core `ProductCard`. This is a code-level override and is not exposed through
-   * the CMS schema (`cms_component__RecommendationShelf.jsonc`).
+   * the CMS schema (`cms_component__recommendationshelf.jsonc`).
    */
   readonly ProductCard?: ComponentType<TCardProps>
   /**

package/src/components/templates/ProductListingPage/ProductListingPage.tsx

@@ -21,6 +21,7 @@ import type { PLPContentType } from 'src/server/cms/plp'
 
 import storeConfig from '../../../../discovery.config'
 import { faststoreLoader } from 'src/components/ui/Image/loader'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import ProductListing from './ProductListing'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 
@@ -142,43 +143,48 @@ export default function ProductListingPage({
     : undefined
 
   return (
-    <SearchProvider
-      onChange={applySearchState}
-      itemsPerPage={itemsPerPage}
-      shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
-      {...searchParams}
+    <LocalizedProductProvider
+      otherLocales={server.collection?.otherLocales}
+      urlSuffix=""
     >
-      {lcpImageUrl && (
-        <Head>
-          <link
-            rel="preload"
-            as="image"
-            href={lcpImageUrl}
-            fetchPriority="high"
-          />
-        </Head>
-      )}
-      {/* SEO */}
-      <NextSeo
-        title={title}
-        description={description}
-        titleTemplate={titleTemplate}
-        canonical={canonical}
-        openGraph={{
-          type: 'website',
-          title,
-          description,
-        }}
-      />
-      <BreadcrumbJsonLd itemListElements={itemListElements} />
-
-      <ProductListing
-        globalSections={globalSections}
-        globalSettings={globalSettings}
-        page={plpContentType}
-        data={server}
-        serverManyProductsVariables={serverManyProductsVariables}
-      />
-    </SearchProvider>
+      <SearchProvider
+        onChange={applySearchState}
+        itemsPerPage={itemsPerPage}
+        shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
+        {...searchParams}
+      >
+        {lcpImageUrl && (
+          <Head>
+            <link
+              rel="preload"
+              as="image"
+              href={lcpImageUrl}
+              fetchPriority="high"
+            />
+          </Head>
+        )}
+        {/* SEO */}
+        <NextSeo
+          title={title}
+          description={description}
+          titleTemplate={titleTemplate}
+          canonical={canonical}
+          openGraph={{
+            type: 'website',
+            title,
+            description,
+          }}
+        />
+        <BreadcrumbJsonLd itemListElements={itemListElements} />
+
+        <ProductListing
+          globalSections={globalSections}
+          globalSettings={globalSettings}
+          page={plpContentType}
+          data={server}
+          serverManyProductsVariables={serverManyProductsVariables}
+        />
+      </SearchProvider>
+    </LocalizedProductProvider>
   )
 }

package/src/components/ui/Breadcrumb/Breadcrumb.tsx

@@ -2,7 +2,6 @@ import type { BreadcrumbProps as UIBreadcrumbProps } from '@faststore/ui'
 import { Breadcrumb as UIBreadcrumb } from '@faststore/ui'
 import { memo } from 'react'
 
-import storeConfig from 'discovery.config'
 import Link from 'src/components/ui/Link'
 import { useOverrideComponents } from 'src/sdk/overrides/OverrideContext'
 export interface BreadcrumbProps extends UIBreadcrumbProps {
@@ -32,17 +31,11 @@ const Breadcrumb = ({ icon, alt, ...otherProps }: BreadcrumbProps) => {
           />
         </Link>
       }
-      renderLink={({ itemProps: { item: link, name } }) =>
-        // workaround to display the name without a link since localized slug is not available yet
-        // TODO: when localized slugs are available remove this workaround
-        storeConfig.localization?.enabled ? (
-          <span data-fs-breadcrumb-link>{name}</span>
-        ) : (
-          <Link data-fs-breadcrumb-link href={link} prefetch={false}>
-            {name}
-          </Link>
-        )
-      }
+      renderLink={({ itemProps: { item: link, name } }) => (
+        <Link data-fs-breadcrumb-link href={link} prefetch={false}>
+          {name}
+        </Link>
+      )}
       {...Breadcrumb.props}
       {...otherProps}
     />

package/src/components/ui/LocalizationButton/LocalizationButton.tsx

@@ -6,6 +6,7 @@ import { Icon, Button as UIButton } from '@faststore/ui'
 import storeConfig from 'discovery.config'
 import LocalizationSelector from 'src/components/localization/LocalizationSelector'
 import { useBindingSelector } from 'src/sdk/localization'
+import { useLocalizedProduct } from 'src/sdk/localization/LocalizedProductContext'
 import { useSession } from 'src/sdk/session'
 
 export interface LocalizationButtonErrorMessages {
@@ -41,6 +42,9 @@ const LocalizationButton = ({
   const [isSelectorOpen, setIsSelectorOpen] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
 
+  const otherLocales = useLocalizedProduct()?.otherLocales ?? undefined
+  const urlSuffix = useLocalizedProduct()?.urlSuffix ?? '/p'
+
   const {
     languages,
     currencies,
@@ -52,7 +56,7 @@ const LocalizationButton = ({
     reset,
     isSaveEnabled,
     error,
-  } = useBindingSelector()
+  } = useBindingSelector(otherLocales, urlSuffix)
 
   const { locale: sessionLocale, currency: sessionCurrency } = useSession()
 

package/src/experimental/index.ts

@@ -82,3 +82,5 @@ export type { UseBindingSelectorReturn } from '../sdk/localization/useBindingSel
 export { useLink as useLink_unstable } from '../sdk/ui/useLink'
 export { default as Link_unstable } from '../components/ui/Link'
 export { localizeRedirectDestination as localizeRedirectDestination_unstable } from '../utils/localization/localizeRedirectDestination'
+export { useLocalizedProduct as useLocalizedProduct_unstable } from '../sdk/localization/LocalizedProductContext'
+export type { LocalizedProductLocale as LocalizedProductLocale_unstable } from '../sdk/localization/LocalizedProductContext'

package/src/pages/[...slug].tsx

@@ -106,6 +106,10 @@ const query = gql(`
           value
         }
       }
+      otherLocales {
+        locale
+        slug
+      }
     }
   }
 `)
@@ -172,6 +176,7 @@ export const getStaticProps: GetStaticProps<
     >({
       variables: { slug },
       operation: query,
+      locale,
     }),
     contentService.getPlpContent(
       {

package/src/pages/[slug]/p.tsx

@@ -34,6 +34,7 @@ import {
   getGlobalSectionsData,
   type GlobalSectionsData,
 } from 'src/components/cms/GlobalSections'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 import { getOfferUrl, useOffer } from 'src/sdk/offer'
 import PageProvider, { type PDPContext } from 'src/sdk/overrides/PageProvider'
@@ -94,6 +95,46 @@ const overwriteMerge = (_: any[], sourceArray: any[]) => sourceArray
 const isClientOfferEnabled = (storeConfig as StoreConfig).experimental
   .enableClientOffer
 
+function buildHreflangLinks(
+  storeConfig: StoreConfig,
+  otherLocales: Array<{ locale: string; slug: string }> | null | undefined
+): Array<{ rel: string; hrefLang: string; href: string }> {
+  if (!storeConfig.localization?.enabled || !otherLocales?.length) return []
+
+  const locales = storeConfig.localization.locales
+  const baseStoreUrl = storeConfig.storeUrl.replace(/\/$/, '')
+  const defaultLocale = storeConfig.localization.defaultLocale
+  const links: Array<{ rel: string; hrefLang: string; href: string }> = []
+
+  for (const { locale, slug } of otherLocales) {
+    const bindingUrl = locales?.[locale]?.bindings?.[0]?.url
+    if (typeof bindingUrl === 'string' && bindingUrl.length > 0) {
+      links.push({
+        rel: 'alternate',
+        hrefLang: locale,
+        href: `${bindingUrl.replace(/\/$/, '')}/${slug}/p`,
+      })
+    }
+  }
+
+  // PREMISE: the default locale is served at the store root (no locale prefix),
+  // which is how Next.js i18n sub-path routing works — the `defaultLocale` has no
+  // prefix while other locales live under `/{locale}`. Hence `x-default` points to
+  // `${storeUrl}/{slug}/p`. If a store ever serves its default locale under a path
+  // prefix or a dedicated domain instead of the root, this href must be derived
+  // from that locale's binding URL instead of `storeUrl`.
+  const defaultEntry = otherLocales.find((e) => e.locale === defaultLocale)
+  if (defaultEntry) {
+    links.push({
+      rel: 'alternate',
+      hrefLang: 'x-default',
+      href: `${baseStoreUrl}/${defaultEntry.slug}/p`,
+    })
+  }
+
+  return links
+}
+
 function Page({
   data: server,
   sections,
@@ -136,6 +177,12 @@ function Page({
       product.offers.offers[0]?.itemCondition ?? ''
     ]
 
+  // hreflang alternate links for multi-locale stores
+  const hreflangLinks = buildHreflangLinks(
+    storeConfig as StoreConfig,
+    server.product.otherLocales
+  )
+
   let itemListElements = product.breadcrumbList.itemListElement ?? []
   if (itemListElements.length !== 0) {
     itemListElements = itemListElements.map(
@@ -245,13 +292,11 @@ function Page({
               ]
             : []),
         ]}
+        additionalLinkTags={hreflangLinks}
         titleTemplate={titleTemplate}
       />
 
-      {/* TODO: when localized slugs are available remove this workaround */}
-      {!storeConfig.localization?.enabled && (
-        <BreadcrumbJsonLd itemListElements={itemListElements} />
-      )}
+      <BreadcrumbJsonLd itemListElements={itemListElements} />
 
       <ProductJsonLd
         id={`${meta.canonical}${settings?.seo?.id ?? ''}`}
@@ -283,13 +328,15 @@ function Page({
         If needed, wrap your component in a <Section /> component
         (not the HTML tag) before rendering it here.
       */}
-      <PageProvider context={context}>
-        <RenderSections
-          sections={sections}
-          globalSections={globalSections}
-          components={COMPONENTS}
-        />
-      </PageProvider>
+      <LocalizedProductProvider otherLocales={server.product.otherLocales}>
+        <PageProvider context={context}>
+          <RenderSections
+            sections={sections}
+            globalSections={globalSections}
+            components={COMPONENTS}
+          />
+        </PageProvider>
+      </LocalizedProductProvider>
     </>
   )
 }
@@ -351,6 +398,11 @@ const query = gql(`
         productGroupID
       }
 
+      otherLocales {
+        locale
+        slug
+      }
+
       ...ProductDetailsFragment_product
     }
   }