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

215 lines
6.7 KiB
Markdown

# 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:
```bash
# 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`)
```env
# 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`)
```env
# 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`)
```typescript
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`)
```typescript
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`)
```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`)
```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:
```typescript
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:**
```bash
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.