fix: Set correct headers for localized academy pages

app/academy/(en)/[[...slug]]/page.tsx

@@ -1,8 +1,9 @@
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
-import { academySource } from "@/lib/source";
+import { academyJaSource, academySource } from "@/lib/source";
 import { DocsChromePage } from "@/components/DocsChromePage";
 import { buildSectionMetadata } from "@/lib/mdx-page";
+import { buildLocalizedAlternates } from "@/lib/localization";
 
 type PageProps = {
   params: Promise<{ slug?: string[] }>;
@@ -21,7 +22,18 @@ export async function generateMetadata({
   const { slug = [] } = await params;
   const page = academySource.getPage(slug);
   if (!page) return { title: "Not Found" };
-  return buildSectionMetadata(page, "academy", "Academy", slug);
+  const hasJapanesePage = Boolean(academyJaSource.getPage(slug));
+
+  return buildSectionMetadata(page, "academy", "Academy", slug, {
+    languages: buildLocalizedAlternates({
+      slug,
+      defaultLocale: "en",
+      routes: {
+        en: "/academy",
+        ...(hasJapanesePage ? { "ja-JP": "/academy/japan" } : {}),
+      },
+    }),
+  });
 }
 
 export function generateStaticParams() {

app/academy/japan/[[...slug]]/page.tsx

@@ -1,8 +1,9 @@
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
-import { academyJaSource } from "@/lib/source";
+import { academyJaSource, academySource } from "@/lib/source";
 import { DocsChromePage } from "@/components/DocsChromePage";
 import { buildSectionMetadata } from "@/lib/mdx-page";
+import { buildLocalizedAlternates } from "@/lib/localization";
 
 type PageProps = {
   params: Promise<{ slug?: string[] }>;
@@ -15,6 +16,7 @@ export default async function JaAcademyPage({ params }: PageProps) {
   return (
     <DocsChromePage
       page={page}
+      bodyChromeProps={{ lang: "ja" }}
       bottomSuffix={
         <div className="mt-10 text-right text-xs italic text-fd-muted-foreground">
           Translation by{" "}
@@ -38,7 +40,18 @@ export async function generateMetadata({
   const { slug = [] } = await params;
   const page = academyJaSource.getPage(slug);
   if (!page) return { title: "Not Found" };
-  return buildSectionMetadata(page, "academy/japan", "Academy", slug);
+  const hasEnglishPage = Boolean(academySource.getPage(slug));
+
+  return buildSectionMetadata(page, "academy/japan", "Academy", slug, {
+    languages: buildLocalizedAlternates({
+      slug,
+      defaultLocale: "en",
+      routes: {
+        ...(hasEnglishPage ? { en: "/academy" } : {}),
+        "ja-JP": "/academy/japan",
+      },
+    }),
+  });
 }
 
 export function generateStaticParams() {

app/japan/page.tsx

@@ -1,16 +1,17 @@
 import type { Metadata } from "next";
 import { JapanLanding } from "@/components/japan/JapanLanding";
+import { buildLocalizedAlternates } from "@/lib/localization";
 
 export const metadata: Metadata = {
   title: "Langfuse Cloud Japan — 東京でホストされるLLMオブザーバビリティ",
   description:
     "Langfuse Cloud Japan — LLMのトレース、プロンプト管理、評価、メトリクスを、AWS ap-northeast-1（東京）とClickHouseで運用。",
   alternates: {
     canonical: "https://langfuse.com/japan",
-    languages: {
-      en: "https://langfuse.com/japan",
-      ja: "https://langfuse.com/japan",
-    },
+    languages: buildLocalizedAlternates({
+      defaultLocale: "ja-JP",
+      routes: { "ja-JP": "/japan" },
+    }),
   },
 };
 

components/DocBodyChrome.tsx

@@ -13,6 +13,7 @@ import type { ReactNode } from "react";
 
 type Props = {
   children: ReactNode;
+  lang?: string;
   /**
    * When false, renders a plain flex-1 div without prose chrome.
    * Used by wide/marketing sections (pricing, etc.).
@@ -33,6 +34,7 @@ type Props = {
  */
 export function DocBodyChrome({
   children,
+  lang,
   withProse = true,
   versionLabel,
 }: Props) {
@@ -48,7 +50,7 @@ export function DocBodyChrome({
   }
 
   return (
-    <DocsBody className="flex-1">
+    <DocsBody className="flex-1" lang={lang}>
       <div className="mx-auto w-full">
         <div
           className={

lib/localization.ts

@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import { buildPageUrl } from "@/lib/og-url";
+
+type Languages = NonNullable<Metadata["alternates"]>["languages"];
+
+export function buildLocalizedAlternates({
+  slug = [],
+  defaultLocale,
+  routes,
+}: {
+  slug?: string[];
+  defaultLocale: string;
+  routes: Record<string, string>;
+}): Languages {
+  const slugPath = slug.length > 0 ? `/${slug.join("/")}` : "";
+  const languages: Record<string, string> = {};
+
+  for (const [locale, basePath] of Object.entries(routes)) {
+    languages[locale] = buildPageUrl(`${basePath}${slugPath}`);
+  }
+
+  if (languages[defaultLocale]) {
+    languages["x-default"] = languages[defaultLocale];
+  }
+
+  return languages;
+}

lib/mdx-page.ts

@@ -110,7 +110,10 @@ export function buildSectionMetadata(
   section: string,
   sectionTitle: string,
   slug: string[],
-  opts?: { canonicalFallback?: string | null },
+  opts?: {
+    canonicalFallback?: string | null;
+    languages?: NonNullable<Metadata["alternates"]>["languages"];
+  },
 ): Metadata {
   const pageData = page.data;
   const pagePath = `/${section}${slug.length > 0 ? `/${slug.join("/")}` : ""}`;
@@ -135,7 +138,10 @@ export function buildSectionMetadata(
   return {
     title: seoTitle,
     description: page.data.description ?? undefined,
-    alternates: { canonical: canonicalUrl },
+    alternates: {
+      canonical: canonicalUrl,
+      ...(opts?.languages ? { languages: opts.languages } : {}),
+    },
     ...(pageData.noindex ? { robots: { index: false, follow: true } } : {}),
     openGraph: {
       images: [{ url: ogImage }],

scripts/generate-sitemap-excludes.js

@@ -68,6 +68,7 @@ function contentPathToRoute(filePath) {
     changelog: "changelog",
     faq: "faq",
     handbook: "handbook",
+    academy: "academy",
     security: "security",
     blog: "blog",
     customers: "users",