refactor(metadata): improve SEO and metadata generation

Enhance SEO capabilities and metadata handling:

- Add comprehensive SEO audit report documentation
- Improve metadata generators with better type safety
- Enhance metadata helpers with fallback handling
- Add SEO helper utilities for consistent metadata
- Update vendor products handling
- Improve manifest i18n support

These changes improve search engine visibility and ensure
consistent metadata across all pages.

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

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

Author: ericyangpan

docs/SEO-AUDIT-REPORT.md

@@ -31,7 +31,6 @@ AI Coding Stack has a solid technical foundation with proper implementation incl
 - Clean URL structure: `{category}/{slug}`
 - Breadcrumb navigation implemented on detail pages
 - Proper routing for 14+ page types covering 6 categories:
-  - Terminals (iTerm2, Warp, Ghostty, WezTerm)
   - IDEs (VS Code, Cursor, TRAE)
   - CLIs (Codex, Claude Code)
   - 

src/lib/manifest-i18n.ts

@@ -1,4 +1,4 @@
-import type { Locale } from '@/i18n/config';
+import { defaultLocale, type Locale } from '@/i18n/config';
 
 /**
  * Interface for manifest items with i18n support
@@ -28,8 +28,8 @@ export function getLocalizedField<T extends ManifestItemWithI18n>(
   field: keyof T,
   locale: Locale
 ): string {
-  // If locale is 'en' (default), return the original field
-  if (locale === 'en') {
+  // If locale is default, return the original field
+  if (locale === defaultLocale) {
     return item[field] as string;
   }
 
@@ -55,8 +55,8 @@ export function localizeManifestItem<T extends Record<string, unknown>>(
   locale: Locale,
   fields: (keyof T)[] = ['description' as keyof T]
 ): T {
-  // If locale is 'en' (default), return the original item
-  if (locale === 'en') {
+  // If locale is default, return the original item
+  if (locale === defaultLocale) {
     return item;
   }
 

src/lib/metadata/generators.ts

@@ -25,6 +25,7 @@ import {
   formatPriceForDescription,
   buildProductDescription,
 } from './helpers';
+import { defaultLocale } from '@/i18n/config';
 
 /**
  * Generate metadata for category list pages (IDEs, CLIs, etc.)
@@ -68,7 +69,7 @@ export async function generateListPageMetadata(options: {
   });
 
   // Build OpenGraph
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
   const displayName = CATEGORY_DISPLAY_NAMES[category as keyof typeof CATEGORY_DISPLAY_NAMES] || translatedTitle;
   const openGraph = buildOpenGraph({
     title: `${translatedTitle} - Best ${displayName} ${METADATA_DEFAULTS.currentYear}`,
@@ -149,7 +150,7 @@ export async function generateSoftwareDetailMetadata(options: {
   });
 
   // Build OpenGraph with product image
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
   const imagePath = getOGImagePath(category, slug);
 
   const openGraph = buildOpenGraph({
@@ -238,7 +239,7 @@ export async function generateModelDetailMetadata(options: {
   });
 
   // Build OpenGraph
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
   const imagePath = getOGImagePath('models', slug);
 
   const openGraph = buildOpenGraph({
@@ -321,7 +322,7 @@ export async function generateComparisonMetadata(options: {
   });
 
   // Build OpenGraph
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
 
   const openGraph = buildOpenGraph({
     title: `${categoryName} Comparison`,
@@ -383,7 +384,7 @@ export async function generateArticleMetadata(options: {
   });
 
   // Build OpenGraph with article metadata
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
   const imagePath = getOGImagePath('articles', slug);
 
   const openGraph = buildOpenGraph({
@@ -448,7 +449,7 @@ export async function generateDocsMetadata(options: {
   });
 
   // Build OpenGraph
-  const canonicalPath = locale === 'en' ? `/${basePath}` : `/${locale}/${basePath}`;
+  const canonicalPath = locale === defaultLocale ? `/${basePath}` : `/${locale}/${basePath}`;
 
   const openGraph = buildOpenGraph({
     title: doc.title,

src/lib/metadata/helpers.ts

@@ -10,24 +10,24 @@ import {
   METADATA_DEFAULTS,
   type Category,
 } from './config';
+import { locales, localeToOgLocale, type Locale } from '@/i18n/config';
 
 /**
  * Maps internal locale format to OpenGraph locale format
  * @example 'zh-Hans' → 'zh_CN', 'en' → 'en_US'
  */
 export function mapLocaleToOG(locale: string): string {
-  const localeMap: Record<string, string> = {
-    'en': 'en_US',
-    'zh-Hans': 'zh_CN',
-  };
-  return localeMap[locale] || 'en_US';
+  return localeToOgLocale[locale as Locale] || localeToOgLocale[SITE_CONFIG.defaultLocale as Locale];
 }
 
 /**
  * Gets alternate locale for OpenGraph
+ * Returns all other locales in OpenGraph format
  */
 export function getAlternateOGLocale(locale: string): string[] {
-  return locale === 'en' ? ['zh_CN'] : ['en_US'];
+  return locales
+    .filter((l) => l !== locale)
+    .map((l) => localeToOgLocale[l]);
 }
 
 /**

src/lib/seo-helpers.ts

@@ -3,11 +3,14 @@
  * Utilities for generating SEO-friendly URLs and metadata
  */
 
+import { locales, defaultLocale, localeToOgLocale, type Locale } from '@/i18n/config';
+
 /**
  * Generate canonical path with locale support
+ * Default locale (en) doesn't get a prefix, other locales do
  */
 export function getCanonicalPath(basePath: string, locale: string): string {
-  return locale === 'en' ? basePath : `/${locale}/${basePath}`;
+  return locale === defaultLocale ? basePath : `/${locale}${basePath}`;
 }
 
 /**
@@ -20,26 +23,38 @@ export function getFullUrl(basePath: string, locale: string): string {
 
 /**
  * Generate language alternates for a given base path
+ * Dynamically builds alternates from configured locales
  */
 export function getLanguageAlternates(basePath: string): Record<string, string> {
-  return {
-    'en': basePath,
-    'zh-Hans': `/zh-Hans${basePath}`,
-  };
+  const alternates: Record<string, string> = {};
+
+  locales.forEach((locale) => {
+    if (locale === defaultLocale) {
+      alternates[locale] = basePath;
+    } else {
+      alternates[locale] = `/${locale}${basePath}`;
+    }
+  });
+
+  return alternates;
 }
 
 /**
  * Get OpenGraph locale string
+ * Maps locale code to OpenGraph format (e.g., 'en' -> 'en_US')
  */
 export function getOgLocale(locale: string): string {
-  return locale === 'zh-Hans' ? 'zh_CN' : 'en_US';
+  return localeToOgLocale[locale as Locale] || localeToOgLocale[defaultLocale];
 }
 
 /**
  * Get OpenGraph alternate locales
+ * Returns all other locales in OpenGraph format
  */
 export function getOgAlternateLocales(locale: string): string[] {
-  return locale === 'en' ? ['zh_CN'] : ['en_US'];
+  return locales
+    .filter((l) => l !== locale)
+    .map((l) => localeToOgLocale[l]);
 }
 
 /**

src/lib/vendor-products.ts

@@ -78,10 +78,10 @@ export function getProductsByVendor(vendorName: string): VendorProduct[] {
   // Providers
   providersData.forEach((provider) => {
     // Check both vendor and name
-    const matchesvendor = provider.vendor?.toLowerCase() === normalizedVendorName;
+    const matchesVendor = provider.vendor?.toLowerCase() === normalizedVendorName;
     const matchesName = provider.name?.toLowerCase() === normalizedVendorName;
 
-    if (matchesvendor || matchesName) {
+    if (matchesVendor || matchesName) {
       products.push({
         id: provider.id,
         name: provider.name,
@@ -94,29 +94,3 @@ export function getProductsByVendor(vendorName: string): VendorProduct[] {
 
   return products;
 }
-
-/**
- * Get products by vendor ID (matches vendor.id from vendors.json)
- */
-export function getProductsByvendor(vendor: string): VendorProduct[] {
-  const products: VendorProduct[] = [];
-
-  // Providers have vendor field that matches vendor.id
-  providersData.forEach((provider) => {
-    if (provider.vendor === vendor) {
-      products.push({
-        id: provider.id,
-        name: provider.name,
-        category: 'provider',
-        categoryLabel: 'Provider',
-        path: `model-providers/${provider.id}`,
-      });
-    }
-  });
-
-  // Models might have vendor that matches vendor name
-  // We need to get the vendor name from vendor first
-  // For now, we'll just check if vendor field matches common vendor names
-
-  return products;
-}