Files
Suman/docs/implementation-plan/phase-05-storefronts-and-next-intl.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

6.7 KiB

Faza 5: Storefronts - Multi-Storefront i Multi-Language (next-intl)

5.1. Svrha i Ciljevi Faze

U ovoj fazi se uspostavljaju dva odvojena webshopa:

  • Webshop DE (apps/storefront-de): Namijenjen tržištu Njemačke (valuta EUR, primarni jezik njemački).
  • Webshop AT (apps/storefront-at): Namijenjen tržištu Austrije (valuta EUR, primarni jezik njemački, sa specifičnim cijenama i skladištem).

Oba webshopa se baziraju na zvaničnom @medusajs/nextjs-starter-template.

Important

Pravilo gotovih rješenja: Strogo je zabranjeno pisati korpu, checkout, korisnički nalog (auth) ili pretragu od nule. Koriste se gotove komponente, server actions i Medusa JS SDK kuke koje dolaze sa zvaničnim starterom.

Svaki storefront dobija svoj NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY, čime Medusa backend automatski servira samo proizvode, cijene i zalihe vezane za odgovarajući Sales Channel.


5.2. Postavljanje Storefront Aplikacija u Monorepou

Iz korijena monorepoa kloniramo zvanični starter za oba webshopa:

# Storefront za Njemačku
npx create-next-app -e https://github.com/medusajs/nextjs-starter-template apps/storefront-de

# Storefront za Austriju
npx create-next-app -e https://github.com/medusajs/nextjs-starter-template apps/storefront-at

# Instalacija next-intl paketa u oba storefronta
pnpm --filter @umbrella/storefront-de add next-intl
pnpm --filter @umbrella/storefront-at add next-intl

5.3. Konfiguracija Environment Varijabli

Storefront DE (apps/storefront-de/.env.local)

# Medusa Backend URL
MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

# Publishable API ključ dodijeljen Sales Channelu za Njemačku (dobijen iz Faze 2)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_de_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Podrazumijevana regija za starter
NEXT_PUBLIC_DEFAULT_REGION=de
PORT=8000

Storefront AT (apps/storefront-at/.env.local)

# Medusa Backend URL
MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

# Publishable API ključ dodijeljen Sales Channelu za Austriju (dobijen iz Faze 2)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_at_yyyyyyyyyyyyyyyyyyyyyyyyyyyy

# Podrazumijevana regija za starter
NEXT_PUBLIC_DEFAULT_REGION=at
PORT=8001

5.4. Integracija next-intl Multi-Language Sistema

Zvanični starter koristi App Router sa parametrom regije (npr. /[countryCode]). Za uvođenje višejezičnosti (npr. njemački i engleski unutar istog webshopa), konfigurišemo next-intl:

1. Ruting Konfiguracija (apps/storefront-de/src/i18n/routing.ts)

import { defineRouting } from "next-intl/routing"
import { createNavigation } from "next-intl/navigation"

export const routing = defineRouting({
  locales: ["de", "en"],
  defaultLocale: "de",
  localePrefix: "as-needed",
})

export const { Link, redirect, usePathname, useRouter } = createNavigation(routing)

2. Request Konfiguracija (apps/storefront-de/src/i18n/request.ts)

import { getRequestConfig } from "next-intl/server"
import { routing } from "./routing"

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale
  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale
  }

  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default,
  }
})

3. Rječnici Prevoda (apps/storefront-de/messages/de.json)

{
  "General": {
    "search": "Pretraži suncobrane...",
    "cart": "Korpa",
    "account": "Moj Račun"
  },
  "Product": {
    "specificationsTitle": "Tehničke Specifikacije Suncobrana",
    "uvProtection": "UV Zaštita",
    "windResistance": "Otpornost na vjetar",
    "fabricWeight": "Gramaža platna",
    "waterproof": "Vodoodbojni stub",
    "mastDiameter": "Promjer nosivog stuba",
    "warranty": "Fabrička garancija",
    "inStock": "Dostupno na stanju",
    "outOfStock": "Trenutno rasprodano",
    "addToCart": "Dodaj u korpu",
    "b2bInquiry": "Zatražite B2B / HoReCa ponudu"
  }
}

4. Rječnici Prevoda (apps/storefront-de/messages/en.json)

{
  "General": {
    "search": "Search parasols...",
    "cart": "Cart",
    "account": "My Account"
  },
  "Product": {
    "specificationsTitle": "Technical Parasol Specifications",
    "uvProtection": "UV Protection",
    "windResistance": "Wind Resistance",
    "fabricWeight": "Fabric Density",
    "waterproof": "Water Column",
    "mastDiameter": "Mast Diameter",
    "warranty": "Manufacturer Warranty",
    "inStock": "In Stock",
    "outOfStock": "Out of Stock",
    "addToCart": "Add to Cart",
    "b2bInquiry": "Request B2B / HoReCa Quote"
  }
}

5. Kombinovani Middleware (apps/storefront-de/src/middleware.ts)

Povezujemo next-intl obradu sa slanjem x-publishable-api-key zaglavlja:

import { NextRequest, NextResponse } from "next/server"
import createIntlMiddleware from "next-intl/middleware"
import { routing } from "./i18n/routing"

const intlMiddleware = createIntlMiddleware(routing)

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Propuštanje statičkih resursa i Next.js internih fajlova
  if (
    pathname.startsWith("/_next") ||
    pathname.startsWith("/api") ||
    pathname.includes(".")
  ) {
    return NextResponse.next()
  }

  // 1. Obrada višejezičnog URL-a
  const response = intlMiddleware(request)

  // 2. Prosljeđivanje Publishable API ključa Medusa klijentu
  const publishableApiKey = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || ""
  response.headers.set("x-publishable-api-key", publishableApiKey)

  return response
}

export const config = {
  matcher: ["/((?!api|_next|.*\\..*).*)"],
}

5.5. Korak-po-Korak Pokretanje i Testiranje

  1. Pokretanje oba storefronta u paraleli:
    pnpm dev
    
    • Storefront DE se pokreće na http://localhost:8000
    • Storefront AT se pokreće na http://localhost:8001
  2. Provjera kataloga po prodajnom kanalu:
    • Otvorite http://localhost:8000/de.
    • Proizvodi se učitavaju koristeći njemački prodajni kanal i valutu EUR.
  3. Provjera višejezičnosti:
    • Otvorite http://localhost:8000/en.
    • Provjerite da li se interfejs prikazuje na engleskom jeziku sa istim proizvodima.

5.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)

  • Oba storefronta se pokreću bez konflikata na definisanim portovima (8000 i 8001).
  • Svaki storefront šalje svoj NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY u zaglavlju svakog zahtjeva prema backendu.
  • next-intl omogućava prebacivanje jezika /de i /en bez gubitka artikala u korpi.
  • Standardni Medusa checkout, login i korpa funkcionišu bez ikakvih modifikacija koda startera.