Terminal
Terminal/Skill
Adds next-intl to the Vercel shop template, giving it locale-prefixed URLs, per-language message files and a language switcher.
By Vercel
Works with
npx skills add vercel/shop --skill enable-i18nAdd next-intl so the storefront serves locale-prefixed URLs (/en-US/products/foo), loads per-locale message catalogs, and exposes a copy-language switcher. The default is one deployment with clean URLs, inline component copy with reusable functions in lib/content/index.ts, and shopConfig.localization = { country: "US", language: "EN", locale: "en-US" }. There is no next-intl dependency, message catalog, lib/i18n/ directory, or lib/params/server.ts locale resolver to reuse in a fresh template.
Use
enable-shopify-marketsinstead for regional commerce. This skill translates storefront copy and adds routing; it must not infer a commerce country from a copy locale or mutate cart buyer country when language changes. Keep Shopify country/language configuration explicit, preserve intentional operation locale/cache inputs, and always display currency from Shopify responses.
Read scoped AGENTS.md, package.json, next.config.ts, lib/config/index.ts, lib/content/index.ts, routes, components, layout, proxy, and any existing localization files. Trace copy consumers, formatting, SEO, markdown, cart, auth, and chat boundaries before editing.
Choose the migration path from evidence:
Confirm the default copy locale and supported copy locales with the user. In a noninteractive run, report any unresolved choice and stop rather than choosing a routing or translation policy.
pnpm add next-intl from the storefront root. Read the installed next-intl plugin/request/routing APIs and local Next.js guides before wiring them. If next-intl already exists, preserve its compatible version rather than reinstalling blindly.lib/i18n/request/server.ts as described below, then create the plugin with createNextIntlPlugin from next-intl/plugin and the explicit request-config path. In the current template, add that plugin to the list passed to withShopConfig(nextConfig, plugins); preserve the conditional withBotId and withEve entries and their existing order. Do not pass the exported async config factory to a plugin that expects a config object. Preserve customized wrapper composition, rewrites, redirects, and Cache Components settings, and do not enable optional features as part of localization.lib/content/index.ts. Create the default catalog from the storefront's actual customized copy, not a template snapshot. Convert functions to equivalent ICU messages with the same parameter names, zero/one/many behavior, number formatting, rich text, and accessibility labels. Do not serialize functions into JSON or build a custom t() parser.getTranslations() from next-intl/server. Pass translated primitive labels to client leaves when possible. For interactive plurals/interpolation, wrap only the relevant leaf in a Server Component's NextIntlClientProvider with the namespaces it uses, then use useTranslations() there. Never pass the full catalog from the root layout, and never pass ordinary copy functions across the server/client boundary. Keep components/ui/ copy-agnostic.<html lang> and UI number/date formatting from the validated copy locale. Leave shopConfig.localization.country and .language as deployment commerce settings unless Shopify content translation is explicitly requested and validated. A copy locale such as fr-FR does not by itself mean shipping/pricing country FR.AGENTS.md to require aligned locale catalogs and scoped providers now that it is localized.On a fresh installation, create lib/i18n/index.ts with the user's approved locales. On an existing installation, extend its current source of truth instead. Routing, sitemap, alternates, and the switcher must read the same list. This list describes copy/routing locales, not a locale-to-currency or commerce-country map.
Example only; replace with the approved list and seed the default from the deployment's formatting locale when appropriate:
import type { Locale } from "./types";
export const locales = ["en-US", "fr-FR"] as const;
export const defaultLocale: Locale = "en-US";
export const enabledLocales: readonly Locale[] = locales;
export function isEnabledLocale(value: string): value is Locale {
return enabledLocales.some((locale) => locale === value);
}
Define the shared Locale contract in lib/i18n/types.ts; import it directly wherever it is needed:
import type { locales } from "./index";
export type Locale = (typeof locales)[number];
Use domain/context files for new modules: universal routing configuration in lib/i18n/routing/index.ts, client navigation in lib/i18n/navigation/client.ts, server request configuration in lib/i18n/request/server.ts, and the root-param resolver in lib/params/server.ts. Do not add barrels or forwarding exports. Preserve working paths in an existing customized installation rather than renaming them solely to match these examples.
Validate route params, action inputs, and request payloads against this list. Retain any existing resolver and fallback policy rather than resetting it.
lib/i18n/routing/index.ts and lib/i18n/navigation/client.ts (next-intl)app/[locale]/ containing every pageproxy.ts middleware running next-intl/middlewarelib/params/server.ts getLocale() reading from next/root-paramslib/i18n/request/server.ts loading messages by resolved localelib/seo/index.tsproxy.tsgenerateStaticParams and the carried ensureStatic on the locale root layoutThe template runs with cacheComponents: true, Partial Prefetching, and export const ensureStatic = "prefetch" on the root layout, which requires the App Shell and per-link prefetches to be static. Skipping any of these produces build errors that look unrelated:
app/layout.tsx above app/[locale]/For [locale] to be recognized as a root param, the dynamic segment must be the root layout. After Step 2, the file at app/layout.tsx should be gone (moved into app/[locale]/layout.tsx). If both exist, rootParams.locale() returns undefined.
ensureStatic and give locale static paramsMove export const ensureStatic = "prefetch" with the root layout into app/[locale]/layout.tsx, and export generateStaticParams there for every enabled locale (Step 11). Cache Components requires at least one value for each root param; without one, the build fails:
Error: A required root parameter (locale) was not provided in generateStaticParams for /[locale]/cart, please provide at least one value.
Keep the nested generateStaticParams exports that return placeholder handles from lib/static-params; Next.js combines them with the layout's locales. A localized page or layout must not set a weaker ensureStatic than the locale layout:
A child segment cannot override a parent segment with a less-constrained `ensureStatic`.
Resolve locale from the root param, never from headers(), cookies(), or searchParams in the shell. A request read outside <Suspense> anywhere under the locale layout fails every localized route:
Error: Route "/[locale]/account/addresses": Next.js encountered uncached or runtime data during prerendering.
Move the read into the smallest Suspense boundary that needs it; next build --debug-prerender reports the source line. Do not set export const instant = false to silence the error: AGENTS.md forbids that opt-out, and it does not relax ensureStatic.
setRequestLocale is not usednext-intl docs sometimes show setRequestLocale(locale) calls in layouts/pages. Don't add them under cacheComponents. That helper writes to a request-scoped store and forces dynamic rendering — it defeats the cache. The rootParams + request-config pattern below makes it unnecessary because the resolved locale is already a cache key.
LinkDo not replace Link from @/components/ui/link with next-intl's Link. The template Link owns intent-based prefetching, and AGENTS.md requires it for every internal link. Pass explicitly locale-prefixed hrefs from a Server Component using its validated locale. Middleware can redirect legacy unprefixed paths, but those redirects may negotiate a different locale and must not be the only mechanism keeping navigation in the selected language.
For Server Component redirects, use next/navigation and an explicitly prefixed path: `/${await getLocale()}/account/login`. next/root-params is not available in Server Actions or Route Handlers: receive and validate locale at those boundaries instead. Do not rely on middleware language detection to preserve the current URL locale; prefer explicit prefixed hrefs passed from the server for ordinary links.
Do not import lib/i18n/navigation/client.ts into a server auth gate. Use next/navigation's redirect (which returns never) and prefix the locale yourself:
import { redirect } from "next/navigation";
import { getLocale } from "@/lib/params/server";
if (!session) redirect(`/${await getLocale()}/account/login`);
return session; // OK, narrowed
Create lib/i18n/routing/index.ts:
import { defineRouting } from "next-intl/routing";
import { defaultLocale, enabledLocales } from "@/lib/i18n";
export const routing = defineRouting({
locales: enabledLocales, // pulled from lib/i18n/index.ts — never hardcode
defaultLocale,
localePrefix: "always",
});
Create lib/i18n/navigation/client.ts:
"use client";
import { createNavigation } from "next-intl/navigation";
import { routing } from "@/lib/i18n/routing";
export const { usePathname, useRouter } = createNavigation(routing);
Per "Cache Components compatibility E", use this navigation only in the locale switcher and other client-side programmatic routing; internal links keep the template
Link.
app/[locale]/Move every route file from app/ into app/[locale]/:
app/layout.tsx → app/[locale]/layout.tsx (becomes the root layout for the locale segment). Delete the original app/layout.tsx after the move — see compatibility A above; both files cannot coexist.app/page.tsx, app/error.tsx, app/not-found.tsx → app/[locale]/...app/account/, app/cart/, app/collections/, app/pages/, app/policies/, app/products/, app/search/ → app/[locale]/...Stay at app/: api/, agent/, md/, llms.txt/, sitemap.xml/, sitemap/, robots.ts, global-error.tsx, globals.css, favicon.ico, icon.svg, apple-icon.png, manifest.ts. Include blogs and any custom storefront pages in the localized route audit; do not limit the move to the example list.
In the moved layout, fix import "./globals.css" → import "../globals.css" and keep every export, including export const ensureStatic = "prefetch", metadata, and viewport.
Update every PageProps<"/foo"> and LayoutProps<"/foo"> generic to include the locale segment: PageProps<"/[locale]/products/[handle]">, LayoutProps<"/[locale]">, etc.
lib/params/server.ts for Server Component root paramsThis is a new module on the simplified baseline. In a customized installation, preserve unrelated helpers and extend its existing resolver. Route Handlers use their route context or validated request inputs; Server Actions receive a validated locale argument, not this getter.
import { notFound } from "next/navigation";
import { locale as rootLocale } from "next/root-params";
import { locales } from "@/lib/i18n";
import type { Locale } from "@/lib/i18n/types";
export async function getLocale(): Promise<Locale> {
const current = await rootLocale();
if (!current || !locales.includes(current as Locale)) notFound();
return current as Locale;
}
lib/i18n/request/server.ts loads messages by resolved localeimport { hasLocale } from "next-intl";
import { getRequestConfig } from "next-intl/server";
import { getLocale } from "@/lib/params/server";
import type enMessages from "@/lib/i18n/messages/en.json";
import { routing } from "@/lib/i18n/routing";
const messageLoaders: Record<string, () => Promise<{ default: typeof enMessages }>> = {
"en-US": () => import("@/lib/i18n/messages/en.json"),
"fr-FR": () => import("@/lib/i18n/messages/fr.json"),
};
// Read the root param, not next-intl's request locale, which reads the
// `x-next-intl-locale` request header and fails the layout's static shell.
export default getRequestConfig(async () => {
const requested = await getLocale();
const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale;
const loader = messageLoaders[locale];
const messages = (await loader()).default as typeof enMessages;
return { locale, messages };
});
proxy.tsCompose next-intl at the end of the existing proxy, where the template returns NextResponse.next(...). Keep everything before that point unchanged: Shopify route dispatch (handleShopifyRoutes() returns null synchronously when Hydrogen does not own the pathname), and Markdown negotiation (Step 9). Pass the forwarded headers through forwardCustomerRefreshAttempt so the account refresh marker still reaches Server Components:
const handleI18n = createMiddleware(routing);
// Keep the existing imports and add NextRequest as a runtime import.
export async function proxy(request: NextRequest): Promise<Response> {
// Keep the template's Shopify dispatch and Markdown negotiation here, unchanged.
const i18nRequest = new NextRequest(request, {
headers: forwardCustomerRefreshAttempt(
request.nextUrl,
requestContext.getForwardedRequestHeaders(),
),
});
const response = handleI18n(i18nRequest);
requestContext.applyResponseHeaders(response.headers);
if (!response.ok) return response;
const rewriteHeader = response.headers.get("x-middleware-rewrite");
if (!rewriteHeader) return response;
const rewriteTarget = new URL(rewriteHeader, request.url);
const [, ...segments] = rewriteTarget.pathname.split("/");
const normalized = new URL(`/${segments.filter(Boolean).join("/")}`, request.url);
normalized.search = rewriteTarget.search;
return NextResponse.rewrite(normalized, { headers: response.headers });
}
Update the matcher. The template's single broad matcher is safe only while the proxy does nothing but Shopify dispatch; with locale negotiation, every request Hydrogen declines is localized, including app Route Handlers, webhooks, robots.txt, sitemaps, llms.txt, and static files. Replace it with Shopify's exact route families, locale-prefixed Shopify endpoints, and a catch-all that skips /api, Eve, Next.js and Vercel internals, and paths with a file extension:
export const config = {
matcher: [
"/api/cart",
"/api/predictive-search",
"/api/mcp",
"/api/ucp/mcp",
"/api/:apiVersion(unstable|2\\d{3}-\\d{2})/graphql.json",
"/__shopify/:path*",
"/.well-known/:path*",
"/agent/:action(handoff|buyer-claims).:format",
"/cart.:format(js|json)",
"/cart/:operation(add|update|change|clear).:format(js|json)",
"/:page(index|search).md",
"/:resource(collections|products)/:handle.md",
"/:locale([a-zA-Z]{2}(?:-[a-zA-Z]{2})?)/agent/:action(handoff|buyer-claims).:format",
"/:locale([a-zA-Z]{2}(?:-[a-zA-Z]{2})?)/cart.:format(js|json)",
"/:locale([a-zA-Z]{2}(?:-[a-zA-Z]{2})?)/cart/:operation(add|update|change|clear).:format(js|json)",
"/((?!api|eve(?:/|$)|_eve_internal(?:/|$)|_next/static|_next/image|_next/data|_vercel|favicon.ico|.*\\..*).*)",
],
};
Downstream applications must be able to add Route Handlers such as /api/webhooks or /api/custom without sending them through Shopify dispatch or locale middleware. If a new Hydrogen feature claims another reserved route, add that exact route family.
Keep Eve's /eve/v1/ and /_eve_internal/ routes outside Shopify dispatch and locale negotiation. Keep /api/agent/session and /agent/ucp-profile.json unlocalized. If Shop Agent is enabled, carry and validate the copy locale explicitly for conversation context and navigation outputs without changing the deployment's Shopify country/language or allowing client context to select a cart. Keep Next.js request/cache APIs out of Eve's runtime imports.
The file is proxy.ts (Next.js 16 convention), not middleware.ts.
LinkPer "Cache Components compatibility E", leave existing Link imports from @/components/ui/link alone and pass locale-prefixed hrefs from the server. Inspect product cards, menus, breadcrumbs, search, cart, and pagination so navigation retains the selected language without a negotiation redirect. Use next-intl's client navigation in the locale switcher when needed, preserving the resource and query parameters. Reuse existing localized link helpers in customized installations.
For programmatic redirects in server code, use next/navigation's redirect:
redirect(`/${await getLocale()}/account/login`);
lib/seo/index.ts — locale-aware canonicals + hreflang alternatesKeep this module universal: callers resolve and validate the locale on the server, then pass it explicitly. Do not import the server root-param resolver into index.ts.
import { defaultLocale, enabledLocales } from "@/lib/i18n";
import type { Locale } from "@/lib/i18n/types";
function withLocalePath(locale: string, pathname: string): string {
const normalized = normalizePath(pathname);
return normalized === "/" ? `/${locale}` : `/${locale}${normalized}`;
}
export function buildAlternates({
locale,
pathname,
searchParams,
}: {
locale: Locale;
pathname: string;
searchParams?: SearchParamsInput;
}): Metadata["alternates"] {
const canonical = buildCanonicalPath(withLocalePath(locale, pathname), searchParams);
const languages: Record<string, string> = {};
for (const candidate of enabledLocales) {
languages[candidate] = buildCanonicalPath(withLocalePath(candidate, pathname), searchParams);
}
languages["x-default"] = buildCanonicalPath(
withLocalePath(defaultLocale, pathname),
searchParams,
);
return { canonical, languages };
}
Update every caller to pass its validated locale. Server Components can call getLocale() from lib/params/server.ts; Route Handlers and Server Actions must validate their own inputs.
Edit app/sitemap/[shard]/route.ts. For every resource, emit one <url> per enabled locale and add <xhtml:link rel="alternate" hreflang="..." href="..." /> siblings inside each <url> pointing at the other locale variants. Add xmlns:xhtml="http://www.w3.org/1999/xhtml" to the <urlset> opening tag.
import { enabledLocales } from "@/lib/i18n";
function localizePath(locale: string, pathname: string): string {
if (pathname === "/") return `/${locale}`;
return `/${locale}${pathname.startsWith("/") ? pathname : `/${pathname}`}`;
}
// Inside renderShard(): for each item, for each locale, emit a <url> with
// a <loc> at the localized path and an <xhtml:link> per other locale.
app/sitemap.xml/route.ts (the index) doesn't need locale handling — it only lists shard URLs, which stay locale-agnostic.
proxy.ts serves Markdown through getMarkdownPath() and getMarkdownMirrorPath() in lib/markdown/representation/index.ts, which map /, /search, /collections/:handle, /products/:handle, and their .md mirrors to the unlocalized app/md/... handlers. Teach both to accept and strip a validated locale prefix so /:locale/products/:handle negotiates like /products/:handle, and keep the localized proxy matcher covering the localized paths. Inspect the handlers before forwarding locale; introduce and validate a copy-locale input where needed rather than assuming they already read it. Keep their deployment commerce context unchanged, and preserve ?variant= and search parameters.
/ and unknown localesWith localePrefix: "always", next-intl's middleware redirects / to the negotiated locale; without the proxy change, / returns 404. Do not add an app/(unlocalized)/page.tsx fallback: a page outside app/[locale]/ has no root layout, and the build fails with (unlocalized)/page.tsx doesn't have a root layout.
Unknown locales and URLs outside every route render Next.js's built-in 404 page, because no root layout applies to them. A branded page needs app/global-not-found.tsx, which is experimental (experimental.globalNotFound) in this Next.js version; add it only when the user accepts that.
generateStaticParams on the locale layoutKeep export const ensureStatic = "prefetch" beside it (see "Cache Components compatibility B"):
import { locales } from "@/lib/i18n";
export const generateStaticParams = async () => {
return locales.map((locale) => ({ locale }));
};
Inspect the current navigation, including any Shopify-menu customization. The simplified template does not ship a dormant LocaleCurrencySelector to re-enable. Add a leaf language selector, or preserve and extend an existing one. Keep the current resource and query parameters when switching. A copy-language switch must not change cart country or invent a currency choice.
After applying:
pnpm lint
pnpm build
pnpm dev
# In another terminal, replace locale/handle with actual supported values:
curl -I http://localhost:3000/
curl -I http://localhost:3000/products/actual-handle
curl http://localhost:3000/sitemap.xml
curl http://localhost:3000/sitemap/products-1.xml
curl http://localhost:3000/en-US
Smoke-test checklist:
/ redirects to default locale<html lang> matches the URL's locale segmentLink hrefs preserve the selected locale; legacy unprefixed public URLs still redirect correctly