Multilingual SEO for SaaS: 12 个语言市场，90 天自然流量增长 47% — 生产级代码实现

// app/router.tsx (tanstack-router@1.135.0)
import { createRouter, createRootRoute, createRoute, createRootRouteWithContext } from '@tanstack/react-router'

export const LOCALES = ['en', 'de', 'fr', 'es', 'pt', 'ja', 'zh', 'ko', 'it', 'nl', 'pl', 'sv'] as const
export type Locale = typeof LOCALES[number]
export const DEFAULT_LOCALE: Locale = 'en'

// 无路径 locale 布局 — 保持 :locale 在 URL 中但移出路由树
const localeLayoutRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '$locale',
  parseParams: (params) => ({
    locale: LOCALES.includes(params.locale as Locale) ? (params.locale as Locale) : DEFAULT_LOCALE,
  }),
  stringifyParams: ({ locale }) => ({ locale }),
  beforeLoad: async ({ params }) => {
    const translations = await loadTranslations(params.locale)
    return { locale: params.locale, translations }
  },
})

const indexRoute = createRoute({
  getParentRoute: () => localeLayoutRoute,
  path: '/',
  component: HomePage,
})

const pricingRoute = createRoute({
  getParentRoute: () => localeLayoutRoute,
  path: '/pricing',
  component: PricingPage,
})

export const routeTree = rootRoute.addChildren([
  localeLayoutRoute.addChildren([indexRoute, pricingRoute, /* … */]),
])

// workers/detect-locale.ts
export function detectLocale(request: Request, urlLocale: string | undefined): Locale {
  if (urlLocale && LOCALES.includes(urlLocale as Locale)) return urlLocale as Locale

  const accept = request.headers.get('Accept-Language') ?? ''
  const preferred = accept.split(',')[0]?.split('-')[0]
  if (preferred && LOCALES.includes(preferred as Locale)) return preferred as Locale

  const country = request.cf?.country as string | undefined
  const countryLocale = COUNTRY_TO_LOCALE[country]
  if (countryLocale) return countryLocale

  return DEFAULT_LOCALE
}

// lib/hreflang.ts
import { LOCALES, DEFAULT_LOCALE, type Locale } from '@/i18n/config'

export interface HreflangEntry {
  hreflang: string  // 'en', 'de', 'x-default'，或用于地区的 'en-GB'
  href: string
}

export function generateHreflang(
  pathname: string,
  baseUrl: string,
  regionalOverrides?: Partial<Record<Locale, string>>,
): HreflangEntry[] {
  const entries: HreflangEntry[] = []

  for (const locale of LOCALES) {
    const region = regionalOverrides?.[locale]
    const code = region ? `${locale}-${region}` : locale
    const url = locale === DEFAULT_LOCALE
      ? `${baseUrl}${pathname}`
      : `${baseUrl}/${locale}${pathname}`
    entries.push({ hreflang: code, href: url })
  }

  // x-default 必须指向默认语言页面上的语言选择器
  entries.push({
    hreflang: 'x-default',
    href: `${baseUrl}${pathname}`,
  })

  return entries
}

// components/HreflangMeta.tsx
export function HreflangMeta({ pathname }: { pathname: string }) {
  const baseUrl = 'https://tanstackship.com'
  const entries = generateHreflang(pathname, baseUrl)
  return (
    <>
      {entries.map((e) => (
        <link key={e.hreflang} rel="alternate" hrefLang={e.hreflang} href={e.href} />
      ))}
    </>
  )
}

// workers/sitemap.xml.ts
import { LOCALES, DEFAULT_LOCALE, type Locale } from '@/i18n/config'
import { generateHreflang } from '@/lib/hreflang'

const SITE_URL = 'https://tanstackship.com'
const PAGES = ['/', '/pricing', '/blog', '/features', '/compare', '/docs']

export async function generateSitemap(): Promise<string> {
  const urls: string[] = []

  for (const page of PAGES) {
    const hreflangEntries = generateHreflang(page, SITE_URL)

    // xhtml:link 条目 — 每个备用语言一个
    const xhtmlLinks = hreflangEntries
      .map((e) => `    <xhtml:link rel="alternate" hreflang="${e.hreflang}" href="${e.href}"/>`)
      .join('\n')

    // 每个语言市场获得自己的 URL 条目指向本地化版本
    for (const locale of LOCALES) {
      const localeUrl = locale === DEFAULT_LOCALE
        ? `${SITE_URL}${page}`
        : `${SITE_URL}/${locale}${page}`
      const alternates = hreflangEntries
        .filter((e) => e.hreflang !== 'x-default')
        .map((e) => `      <xhtml:link rel="alternate" hreflang="${e.hreflang}" href="${e.href}"/>`)
        .join('\n')

      urls.push(`  <url>
    <loc>${localeUrl}</loc>
    <lastmod>${new Date().toISOString()}</lastmod>
    <changefreq>weekly</changefreq>
${alternates}
  </url>`)
    }
  }

  return `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
${urls.join('\n')}
</urlset>`
}

// components/JsonLd.tsx
import { type Locale } from '@/i18n/config'

interface WebPageSchemaProps {
  locale: Locale
  pathname: string
  title: string
  description: string
}

export function WebPageSchema({ locale, pathname, title, description }: WebPageSchemaProps) {
  const schema = {
    '@context': 'https://schema.org',
    '@type': 'WebPage',
    name: title,
    description,
    inLanguage: locale,
    url: `https://tanstackship.com/${locale}${pathname}`,
    isPartOf: {
      '@type': 'WebSite',
      name: 'TanStack Ship',
      url: 'https://tanstackship.com',
      inLanguage: LOCALES,
    },
  }

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  )
}

// components/LocaleSwitcher.tsx
export function LocaleSwitcher({ currentLocale }: { currentLocale: Locale }) {
  const router = useRouter()
  const pathname = useLocation({ select: (l) => l.pathname.replace(/^\/[a-z]{2}(\/|$)/, '$1') })

  const switchTo = (newLocale: Locale) => {
    const newPath = newLocale === DEFAULT_LOCALE
      ? pathname
      : `/${newLocale}${pathname}`
    router.navigate({ to: newPath })
  }

  return (
    <select
      value={currentLocale}
      onChange={(e) => switchTo(e.target.value as Locale)}
    >
      {LOCALES.map((l) => (
        <option key={l} value={l}>{LOCALE_NAMES[l]}</option>
      ))}
    </select>
  )
}

// workers/_middleware.ts
export async function handle(request: Request, env: Env): Promise<Response> {
  const url = new URL(request.url)
  const hasLocale = LOCALES.some((l) => url.pathname.startsWith(`/${l}/`) || url.pathname === `/${l}`)
  const isAsset = url.pathname.startsWith('/_assets/') || url.pathname.startsWith('/api/')

  if (!hasLocale && !isAsset && request.method === 'GET') {
    const locale = detectLocale(request, undefined)
    if (locale !== DEFAULT_LOCALE) {
      return Response.redirect(`${url.origin}/${locale}${url.pathname}${url.search}`, 302)
    }
  }
  return env.ASSETS.fetch(request)
}

// scripts/check-hreflang.ts
import { routeTree } from '../app/router'
import { LOCALES, DEFAULT_LOCALE } from '../i18n/config'
import { generateHreflang } from '../lib/hreflang'

const SITE_URL = 'https://tanstackship.com'

// 遍历每个路由并验证 hreflang 集群是否完整
const errors: string[] = []
const seenPaths = new Set<string>()

function walk(route: any, prefix = '') {
  const path = `${prefix}${route.path ?? ''}`
  if (route.children) {
    for (const child of route.children) walk(child, path === '/' ? '' : path)
  } else if (path && !path.startsWith('$')) {
    seenPaths.add(path)
  }
}
walk(routeTree)

for (const pathname of seenPaths) {
  const entries = generateHreflang(pathname, SITE_URL)
  // 每个语言市场必须恰好出现一次
  const codes = entries.map((e) => e.hreflang).filter((c) => c !== 'x-default')
  const expected = new Set(LOCALES)
  const actual = new Set(codes)
  if (codes.length !== expected.size || [...expected].some((l) => !actual.has(l))) {
    errors.push(`${pathname}: hreflang 集群有 ${codes.length} 个条目，预期 ${expected.size}`)
  }
  // x-default 必须存在
  if (!entries.some((e) => e.hreflang === 'x-default')) {
    errors.push(`${pathname}: 缺少 x-default hreflang`)
  }
}

if (errors.length) {
  console.error('hreflang CI 检查失败：\n' + errors.join('\n'))
  process.exit(1)
}
console.log(`hreflang CI 检查通过：${seenPaths.size} 个路径 × ${LOCALES.length} 个语言市场`)