feat(docs): emit canonical + hreflang on doc pages

Move the locale-URL/hreflang logic into lib/seo.ts and reuse it from
both the sitemap and per-page metadata. Each doc page now declares a
self-referential canonical and a full hreflang set (all 7 locales +
x-default -> English), the stronger per-page SEO signal that the
sitemap alone could not provide.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

apps/docs/app/[lang]/docs/[[...slug]]/page.tsx

@@ -9,6 +9,7 @@ import { File, Folder, Files } from 'fumadocs-ui/components/files';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { LLMCopyButton, ViewOptions } from '@/components/ai/page-actions';
 import { gitConfig } from '@/lib/layout.shared';
+import { languageAlternates, localeUrl } from '@/lib/seo';
 
 export default async function Page(props: {
   params: Promise<{ lang: string; slug?: string[] }>;
@@ -60,8 +61,15 @@ export async function generateMetadata(props: {
   const page = source.getPage(params.slug ?? [], params.lang);
   if (!page) notFound();
 
+  // Logical path is locale-independent; reconstruct each locale URL from slugs.
+  const path = ['docs', ...page.slugs].join('/');
+
   return {
     title: page.data.title,
     description: page.data.description,
+    alternates: {
+      canonical: localeUrl(params.lang, path),
+      languages: languageAlternates(path),
+    },
   };
 }

apps/docs/app/sitemap.ts

@@ -1,29 +1,7 @@
 import type { MetadataRoute } from 'next';
 import { source } from '@/lib/source';
 import { i18n } from '@/lib/i18n';
-
-// Canonical production host. Keep in sync with middleware's domain redirect.
-const BASE = 'https://docs.objectos.ai';
-
-// Build an absolute URL for a given locale, hiding the prefix for the
-// default language (matches i18n.hideLocale = 'default-locale').
-function localize(lang: string, path: string): string {
-  const suffix = path ? `/${path}` : '';
-  return lang === i18n.defaultLanguage
-    ? `${BASE}${suffix}`
-    : `${BASE}/${lang}${suffix}`;
-}
-
-// hreflang alternates map for a logical path, linking every locale version
-// plus an x-default that points at the English (canonical) URL.
-function alternates(path: string): Record<string, string> {
-  const languages: Record<string, string> = {};
-  for (const lang of i18n.languages) {
-    languages[lang] = localize(lang, path);
-  }
-  languages['x-default'] = localize(i18n.defaultLanguage, path);
-  return languages;
-}
+import { languageAlternates, localeUrl } from '@/lib/seo';
 
 export const revalidate = false;
 
@@ -45,13 +23,13 @@ export default function sitemap(): MetadataRoute.Sitemap {
     .map((page) => ({ path: ['docs', ...page.slugs].join('/'), priority: 0.8 }));
 
   for (const { path, priority } of [...staticPaths, ...docPaths]) {
-    const langAlternates = alternates(path);
+    const languages = languageAlternates(path);
     for (const lang of i18n.languages) {
       entries.push({
-        url: localize(lang, path),
+        url: localeUrl(lang, path),
         changeFrequency: 'weekly',
         priority,
-        alternates: { languages: langAlternates },
+        alternates: { languages },
       });
     }
   }

apps/docs/lib/seo.ts

@@ -0,0 +1,30 @@
+import { i18n } from '@/lib/i18n';
+
+// Canonical production host. Keep in sync with middleware's domain redirect.
+export const SITE_URL = 'https://docs.objectos.ai';
+
+/**
+ * Absolute URL for a logical (locale-independent) path, hiding the locale
+ * prefix for the default language (matches i18n.hideLocale = 'default-locale').
+ * `path` has no leading slash, e.g. '' (home) or 'docs/architecture'.
+ */
+export function localeUrl(lang: string, path: string): string {
+  const suffix = path ? `/${path}` : '';
+  return lang === i18n.defaultLanguage
+    ? `${SITE_URL}${suffix}`
+    : `${SITE_URL}/${lang}${suffix}`;
+}
+
+/**
+ * hreflang alternates map for a logical path: every supported locale plus an
+ * x-default pointing at the English (canonical) URL. Shape matches the
+ * `alternates.languages` field of Next.js Metadata and MetadataRoute.Sitemap.
+ */
+export function languageAlternates(path: string): Record<string, string> {
+  const languages: Record<string, string> = {};
+  for (const lang of i18n.languages) {
+    languages[lang] = localeUrl(lang, path);
+  }
+  languages['x-default'] = localeUrl(i18n.defaultLanguage, path);
+  return languages;
+}