Next.js sitemap hreflang for App Router and static export: @pas7/nextjs-sitemap-hreflang
A practical guide to Next.js sitemap hreflang for App Router and static export: generate hreflang alternates and x-default, inject or fix sitemap.xml, validate hreflang in CI, and support mixed content pipelines.
The hard part is usually not creating one multilingual sitemap. The hard part is keeping alternate language URLs correct as the site grows. Static pages may follow one locale pattern, content hubs another, and detail pages a third. In practice, a single multilingual site often mixes homepage routing, localized hubs, and locale-segment detail pages. [1][2]
Next.js App Router gives you a clean way to generate sitemap entries through MetadataRoute.Sitemap, but it does not solve every hreflang routing rule for you. The official docs define the sitemap file convention and output shape, while a package like this fills the gap around alternate-language linking and route-aware validation. [1][4]
Google’s hreflang guidance also raises the bar a bit. Alternate URLs should be fully qualified, pages should reference themselves and their alternates, and x-default can be useful for language-neutral fallback pages. That is manageable in a small site, but easy to get wrong when URLs come from multiple pipelines. [5][6]
The quickest entry point is App Router generation with a routing helper and withHreflangFromRouting.
Wrap entries with hreflang generation
The README quick start uses withHreflangFromRouting(entries, routing, { baseUrl, ensureXDefault: true }), which keeps the sitemap generation close to normal App Router code. [1]
The routing helpers are where the package becomes more than a small hreflang wrapper.
| Comparison point | Pattern | Typical use |
|---|---|---|
| Prefix as needed | Home pages and simple localized routes such as /, /uk, /de | Useful when the default locale should stay unprefixed and other locales need a prefix |
| Suffix locale | Content hubs and static pages such as /blog/uk or /contact/uk | Useful when hub pages follow a suffix locale pattern instead of a prefixed path |
| Locale segment | Detail pages such as /blog/en/slug or /blog/uk/slug | Useful when content entries need stable locale-aware detail routing |
| Mixed prefix pages | Optional exceptions such as /uk/about alongside other route styles | Useful when one site mixes several legacy or section-based routing rules |
A lot of teams do not generate sitemap entries directly from one TypeScript array. They already have manifests, frontmatter exports, or CMS-normalized data.
That image support is a nice detail because it matches how many modern static sites actually store content. A post may have one main cover plus several nested screenshots. The docs show how to extract both into the sitemap entry rather than only keeping the top-level URL. [1]
A minimal example from the README looks like this:
import { createSitemapEntriesFromManifest } from "@pas7/nextjs-sitemap-hreflang";
const entries = createSitemapEntriesFromManifest(blogManifest, {
baseUrl: "https://pas7.com.ua",
sectionPath: "/blog",
defaultLocale: "en",
routeStyle: "locale-segment",
});Manifest helper
createSitemapEntriesFromManifest is meant for pipelines that already output slug, locales, and date fields. That keeps sitemap generation aligned with existing content manifests instead of duplicating route logic. [1]
Mixed source support
The package explicitly supports .ts, .json, .md/.mdx, and CMS-driven content pipelines, which makes it easier to use across different content sources in one Next.js project. [1]
Images in sitemap entries
The helper can also include images through imagesFor, which is useful when sitemap entries should carry image URLs from nested content fields like hero covers and section screenshots. [1]
Why this matters
The package fits better into real content systems because it can start from the manifests and data sources teams already have. [1]
The CLI is small, but the split between check and inject is useful.
Use check
Use inject
Best when the site already emits a sitemap file and you want to inject or fix hreflang directly in generated XML during a postbuild step. [1]
Use --prefer when the source file location matters
The CLI can auto-detect public/sitemap.xml, out/sitemap.xml, or sitemap.xml, but explicit preference is safer when the pipeline has more than one candidate output. [1]
The exit codes and JSON format make the package easier to automate than tools that only print human-oriented warnings.
This is one of the quieter strengths of the package. The CLI does not just say that validation failed; it distinguishes missing input, XML failures, and validation errors. That makes pipeline behavior much easier to reason about. [1]
The report format is similarly practical: ok, issues[], summary.byCode, inputPath, and timingMs. Those fields are exactly the kind of contract that CI jobs or dashboards can consume without guesswork. [1][3]
The package is direct, but multilingual sitemap workflows still go wrong in familiar ways.
Keeping sitemap alternates separate from the content pipeline. That usually leads to stale locale clusters or missing entries. [1]
These official sources support the package behavior, Next.js sitemap context, and hreflang guidance used in this article.
The difficult part is usually not adding hreflang once. It is keeping alternates, route patterns, XML output, and CI checks aligned as the site grows.
PAS7 Studio can help turn that into a repeatable multilingual SEO pipeline with cleaner routing rules, safer sitemap validation, and fewer hreflang surprises after deployment.
Related Articles
AI SEO / GEO in 2026: Your Next Customers Aren’t Humans — They’re Agents
Search is shifting from clicks to answers. Bots and AI agents crawl, cite, recommend, and increasingly buy. Learn what AI SEO / GEO means, why classic SEO is no longer enough, and how PAS7 Studio helps brands win visibility in the agentic web.
The most powerful Apple chip yet? M5 Pro and M5 Max are breaking records
A data-backed March 2026 analysis of Apple M5 Pro and M5 Max. We break down why these chips can credibly be called Apple's most powerful pro laptop silicon, how they compare with M4 Pro, M4 Max, M1 Pro, M1 Max, and how they stack up against Intel and AMD laptop rivals.
Automatic Tagging & Search for Saved Links
Integrate with GDrive/S3/Notion for automatic tagging and fast search via search APIs
Bot Development & Automation Services
Professional Telegram bot development and business process automation: chatbots, AI assistants, CRM integrations, workflow automation.
Professional development for your business
We create modern web solutions and bots for businesses. Learn how we can help you achieve your goals.