nextjs-i18n-seo

Audit/fix Next.js i18n SEO for the App Router — crawlability, 307→301 redirects, locale URLs, sitemap, hreflang. Use when diagnosing lost PageRank or i18n redirect bugs in middleware.

SKILL.md

GitHub

Next.js i18n SEO Fix

Multilingual Next.js sites commonly ship with a crawlability-killing bug: locale redirects that use 307 Temporary instead of 301 Permanent. This means Googlebot never transfers PageRank to the actual indexed URL. Fix this first — it's a one-line change with immediate impact.

The Core Problem

When a user (or Googlebot) hits /hexagrams/14, Next.js middleware redirects to /en/hexagrams/14. The default NextResponse.redirect(url) issues a 307 Temporary Redirect. Google does not transfer PageRank on 307s. Result: any backlink to the clean URL is wasted.

Pages Router doesn't have this problem because getStaticPaths generates pages at their final URL with no redirect hop.


Phase 1: Audit the Site

1. Check the redirect status code

curl -I https://example.com/some-page
# Look for: Location: and HTTP/2 301 vs 307

2. Check robots.txt

https://example.com/robots.txt
  • All paths should be allowed (or only /api/ blocked)
  • Sitemap URL must be listed

3. Check the sitemap

https://example.com/sitemap.xml
  • Are all pages listed with their final (locale-prefixed) URL?
  • Are alternates.languages hreflang entries present?

4. Inspect the middleware

Look for NextResponse.redirect(url) — if no status code is passed, it's a 307.


Phase 2: Fix the 307 → 301 Bug

File: src/middleware.ts (or middleware.ts at root)

// ❌ BEFORE — issues 307 Temporary Redirect
const response = NextResponse.redirect(newUrl);

// ✅ AFTER — issues 301 Permanent Redirect (passes PageRank)
const response = NextResponse.redirect(newUrl, 301);

Also fix any locale alias redirects (e.g. zh-hans → zh-CN) the same way — they should already be 301 if added later, but verify.

Commit message:

fix: change locale redirect from 307 to 301 for SEO PageRank transfer

Phase 3 (Optional but Recommended): No-Prefix Default Locale

The locale prefix (/en/hexagrams/14) adds an extra path segment vs. /hexagrams/14. For English-first sites, removing the prefix from the default locale gives cleaner URLs and eliminates the redirect entirely for the primary language.

Middleware changes

const defaultLocale = 'en';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const pathnameHasLocale = nonDefaultLocales.some(
    (l) => pathname.startsWith(`/${l}/`) || pathname === `/${l}`
  );

  // Already has a non-default locale — pass through
  if (pathnameHasLocale) return NextResponse.next();

  // Has explicit /en/ prefix — strip it (301 to clean URL)
  if (pathname.startsWith('/en/') || pathname === '/en') {
    const url = request.nextUrl.clone();
    url.pathname = pathname.replace(/^\/en/, '') || '/';
    return NextResponse.redirect(url, 301);
  }

  // No locale prefix — serve as default (English) directly, no redirect
  return NextResponse.next();
}

generateStaticParams changes

// Layout and page components: include '' (no prefix) for English
export async function generateStaticParams() {
  return [
    { locale: '' },      // English — served at root paths
    { locale: 'zh-CN' },
    { locale: 'zh-TW' },
  ];
}

Sitemap changes

// English URLs use no prefix
const enUrl = `${baseUrl}/hexagrams/${h.id}`;
// Other locales keep prefix
const zhCNUrl = `${baseUrl}/zh-CN/hexagrams/${h.id}`;

Hreflang

<link rel="alternate" hreflang="en" href="https://example.com/hexagrams/14" />
<link rel="alternate" hreflang="zh-CN" href="https://example.com/zh-CN/hexagrams/14" />
<link rel="alternate" hreflang="x-default" href="https://example.com/hexagrams/14" />

Checklist

[ ] curl -I site.com/some-page → confirm 301 (not 307)
[ ] curl -I site.com/en/some-page → confirm 301 to /some-page (if no-prefix)
[ ] sitemap.xml lists final URLs (no redirect hops)
[ ] hreflang present on all pages with x-default
[ ] robots.txt allows all content paths, blocks /api/
[ ] generateStaticParams covers all locale variants
[ ] No cookie-only locale detection (Googlebot ignores cookies)

Why Pages Router Appeared Better

Pages Router with getStaticPaths serves pages at their exact URL with zero redirect hops. App Router with locale middleware adds a redirect layer. The framework itself isn't the problem — the redirect type (307 vs 301) and the locale URL strategy are what matter. App Router with 301 redirects and/or no-prefix default locale matches or exceeds Pages Router crawlability.


Real-World Comparison

sixlines.online (App Router) bookofchanges.academy (Pages Router)
Hexagram URL /en/hexagrams/14 /hexagrams/14
Redirect on clean URL 307 → locale URL ❌ none ✅
Sitemap entries 192 (64 × 3 locales) 64
Middleware on every req yes no
Fix Change to 301 + consider no-prefix —