fix: add crawlable language links and alternate language metadata

Add HiddenLanguageLinks component that renders hidden anchor tags for each language variant, making them discoverable by crawlers and search engines. Update Layout to include this component at the bottom of the page. Update MDXWrapper to generate and pass alternate language links to the Head component for proper SEO signaling.

This ensures that all language variants of documentation pages are discoverable by basic crawlers (curl, wget) and properly indexed by search engines.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: jamiehenson

src/components/Layout/HiddenLanguageLinks.tsx

@@ -0,0 +1,51 @@
+import { useLocation } from '@reach/router';
+import { useLayoutContext } from 'src/contexts/layout-context';
+import { languageData, languageInfo } from 'src/data/languages';
+import { LanguageKey } from 'src/data/languages/types';
+
+/**
+ * HiddenLanguageLinks
+ *
+ * Renders hidden anchor tags for each available language option on the current page.
+ * These links are invisible to users but crawlable by search engines and other web crawlers,
+ * allowing them to discover all language variants of the documentation.
+ *
+ * This component should be placed at the bottom of the page layout.
+ */
+const HiddenLanguageLinks = () => {
+  const { activePage } = useLayoutContext();
+  const location = useLocation();
+  const languageVersions = languageData[activePage.product ?? 'pubsub'];
+
+  // Filter languages to match what's available on this page
+  const availableLanguages = Object.entries(languageVersions)
+    .filter(([lang]) => (activePage.languages ? activePage.languages.includes(lang as LanguageKey) : true))
+    .map(([lang, version]) => ({
+      label: lang as LanguageKey,
+      version,
+    }));
+
+  // Only render if there are multiple language options
+  if (availableLanguages.length <= 1) {
+    return null;
+  }
+
+  return (
+    <nav className="sr-only" aria-hidden="true">
+      <ul>
+        {availableLanguages.map((language) => {
+          const langInfo = languageInfo[language.label];
+          return (
+            <li key={language.label}>
+              <a href={`${location.pathname}?lang=${language.label}`}>
+                {langInfo?.label || language.label} v{language.version}
+              </a>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+};
+
+export default HiddenLanguageLinks;

src/components/Layout/Layout.tsx

@@ -13,6 +13,7 @@ import GlobalLoading from '../GlobalLoading/GlobalLoading';
 import Header from './Header';
 import LeftSidebar from './LeftSidebar';
 import RightSidebar from './RightSidebar';
+import HiddenLanguageLinks from './HiddenLanguageLinks';
 
 export type Frontmatter = {
   title: string;
@@ -49,6 +50,7 @@ const Layout: React.FC<LayoutProps> = ({ children, pageContext }) => {
         </Container>
         {rightSidebar ? <RightSidebar /> : null}
       </div>
+      <HiddenLanguageLinks />
     </GlobalLoading>
   );
 };

src/components/Layout/MDXWrapper.tsx

@@ -28,10 +28,11 @@ import { languageData } from 'src/data/languages';
 import { ActivePage } from './utils/nav';
 import { Table, TableHead, TableBody, TableRow, TableHeader, TableCell } from './mdx/tables';
 import { Tiles } from './mdx/tiles';
-import { Head } from '../Head';
+import { Head, AlternateLanguageLink } from '../Head';
 import { useSiteMetadata } from 'src/hooks/use-site-metadata';
 import { ProductName } from 'src/templates/template-data';
 import { getMetaTitle } from '../common/meta-title';
+import { LanguageKey } from 'src/data/languages/types';
 import UserContext from 'src/contexts/user-context';
 
 type MDXWrapperProps = PageProps<unknown, PageContextType>;
@@ -184,6 +185,23 @@ const MDXWrapper: React.FC<MDXWrapperProps> = ({ children, pageContext, location
   const { canonicalUrl } = useSiteMetadata();
   const canonical = canonicalUrl(location.pathname);
 
+  // Generate alternate language links for SEO
+  const alternateLanguageLinks: AlternateLanguageLink[] = useMemo(() => {
+    if (!pageContext.languages || pageContext.languages.length <= 1) {
+      return [];
+    }
+
+    const product = activePage.product === 'home' ? 'pubsub' : activePage.product;
+    const productLanguages = languageData[product ?? 'pubsub'];
+
+    return pageContext.languages
+      .filter((lang) => productLanguages && productLanguages[lang as LanguageKey])
+      .map((lang) => ({
+        lang,
+        href: canonicalUrl(`${location.pathname}?lang=${lang}`),
+      }));
+  }, [pageContext.languages, activePage.product, location.pathname, canonicalUrl]);
+
   // Use the copyable headers hook
   useCopyableHeaders();
 
@@ -206,7 +224,14 @@ const MDXWrapper: React.FC<MDXWrapperProps> = ({ children, pageContext, location
 
   return (
     <SDKContext.Provider value={{ sdk, setSdk }}>
-      <Head title={title} metaTitle={metaTitle} canonical={canonical} description={description} keywords={keywords} />
+      <Head
+        title={title}
+        metaTitle={metaTitle}
+        canonical={canonical}
+        description={description}
+        keywords={keywords}
+        alternateLanguageLinks={alternateLanguageLinks}
+      />
       <Article>
         <MarkdownProvider
           components={{