fix: page lang, body-text contrast, and per-page SEO/social metadata (#89)

schwannden · web-flow · commit 93ef484ff2e8 · 2026-06-16T11:16:26.000+08:00
diff --git a/index.html b/index.html
@@ -1,29 +1,25 @@
 <!doctype html>
-<html lang="en">
+<html lang="zh-Hant-TW">
   <head>
     <meta charset="UTF-8" />
     <meta
       name="viewport"
       content="width=device-width, initial-scale=1.0, viewport-fit=cover"
     />
-    <title>Weekly Prayers for Nations| SIM Taiwan</title>
-    <meta
-      name="description"
-      content="Weekly Prayers for the Nations from SIM"
-    />
     <meta name="author" content="SIM Taiwan" />
 
-    <meta property="og:title" content="sim-weekly-prayers-hub" />
-    <meta
-      property="og:description"
-      content="Weekly Prayers for the Nations from SIM"
-    />
+    <!--
+      Title, description and og:title/og:description/og:image are set per-page at
+      runtime by react-helmet-async (see src/components/SeoHead.tsx) and captured
+      into each prerendered snapshot. They are intentionally NOT declared
+      statically here: Helmet appends its managed tags without removing static
+      ones, so duplicating them would leave two of each in every snapshot and
+      social crawlers would pick the generic static value over the per-page one.
+    -->
     <meta property="og:type" content="website" />
-    <meta property="og:image" content="/twitter-card.png" />
 
     <meta name="twitter:card" content="summary_large_image" />
     <meta name="twitter:site" content="@sim_taiwan" />
-    <meta name="twitter:image" content="/twitter-card.png" />
 
     <!-- PWA Manifest -->
     <link rel="manifest" href="/manifest.json" />
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -40,6 +40,7 @@
     "next-themes": "^0.4.6",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
+    "react-helmet-async": "^3.0.0",
     "react-hook-form": "^7.63.0",
     "react-i18next": "^15.6.1",
     "react-markdown": "^10.1.0",
diff --git a/scripts/prerender.mjs b/scripts/prerender.mjs
@@ -76,16 +76,21 @@ async function snapshot(route) {
     // Wait until the app has rendered real content into #root — specifically,
     // past the "載入中..." / "Loading..." placeholder that all list/detail pages
     // show while their Supabase fetch is in flight. Without this the snapshot
-    // can capture the loading state. Falls through after the timeout so a page
-    // that genuinely never resolves still gets snapshotted as-is.
+    // can capture the loading state. We also require react-helmet-async to have
+    // applied the per-page <head> (it marks managed tags with `data-rh`), so the
+    // snapshot carries page-specific title/description/og rather than the static
+    // index.html shell — every public route renders a <SeoHead>. Falls through
+    // after the timeout so a page that genuinely never resolves still gets
+    // snapshotted as-is.
     await page
       .waitForFunction(
         () => {
           const root = document.getElementById('root');
           if (!root) return false;
           const text = (root.innerText || '').trim();
           if (text.length <= 50) return false;
-          return !/載入中|Loading/i.test(text);
+          if (/載入中|Loading/i.test(text)) return false;
+          return Boolean(document.querySelector('title[data-rh]'));
         },
         { timeout: 20000 }
       )
diff --git a/src/App.tsx b/src/App.tsx
@@ -2,6 +2,7 @@ import { Toaster } from '@/components/ui/toaster';
 import { Toaster as Sonner } from '@/components/ui/sonner';
 import { TooltipProvider } from '@/components/ui/tooltip';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { HelmetProvider } from 'react-helmet-async';
 import { BrowserRouter, Routes, Route, useNavigate } from 'react-router-dom';
 import { ThemeProvider } from 'next-themes';
 import { FontProvider } from '@/contexts/FontContext';
@@ -54,25 +55,27 @@ function AppRoutes() {
 }
 
 const App = () => (
-  <QueryClientProvider client={queryClient}>
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-      <FontProvider>
-        <TooltipProvider>
-          <Toaster />
-          <Sonner />
-          <BrowserRouter>
-            <div className="min-h-screen bg-background flex flex-col">
-              <Navigation />
-              <main className="flex-1">
-                <AppRoutes />
-              </main>
-              <Footer />
-            </div>
-          </BrowserRouter>
-        </TooltipProvider>
-      </FontProvider>
-    </ThemeProvider>
-  </QueryClientProvider>
+  <HelmetProvider>
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+        <FontProvider>
+          <TooltipProvider>
+            <Toaster />
+            <Sonner />
+            <BrowserRouter>
+              <div className="min-h-screen bg-background flex flex-col">
+                <Navigation />
+                <main className="flex-1">
+                  <AppRoutes />
+                </main>
+                <Footer />
+              </div>
+            </BrowserRouter>
+          </TooltipProvider>
+        </FontProvider>
+      </ThemeProvider>
+    </QueryClientProvider>
+  </HelmetProvider>
 );
 
 export default App;
diff --git a/src/components/SeoHead.tsx b/src/components/SeoHead.tsx
@@ -0,0 +1,41 @@
+import { Helmet } from 'react-helmet-async';
+import { useTranslation } from 'react-i18next';
+
+interface SeoHeadProps {
+  /** Page-specific title; the localized brand suffix is appended automatically. */
+  title: string;
+  /** Plain-text description for <meta name="description"> and og:description. */
+  description?: string;
+  /** Absolute image URL for og:image (e.g. a Supabase Storage URL). */
+  image?: string;
+}
+
+// Site-wide social-share fallback used when a page has no image of its own.
+const DEFAULT_OG_IMAGE = '/twitter-card.png';
+
+/**
+ * Sets per-page document head (title + description + Open Graph) via
+ * react-helmet-async. On live visits this keeps the browser-tab title and
+ * social-share metadata correct per route; at build time the prerender step
+ * (scripts/prerender.mjs) waits for these tags before snapshotting, so AI
+ * crawlers and search engines see unique metadata per page instead of the
+ * static index.html shell.
+ */
+const SeoHead = ({ title, description, image }: SeoHeadProps) => {
+  const { t } = useTranslation();
+  const suffix = t('meta.titleSuffix');
+  const fullTitle = title ? `${title} | ${suffix}` : suffix;
+
+  return (
+    <Helmet>
+      <title>{fullTitle}</title>
+      <meta property="og:title" content={fullTitle} />
+      {description && <meta name="description" content={description} />}
+      {description && <meta property="og:description" content={description} />}
+      <meta property="og:image" content={image || DEFAULT_OG_IMAGE} />
+      <meta name="twitter:image" content={image || DEFAULT_OG_IMAGE} />
+    </Helmet>
+  );
+};
+
+export default SeoHead;
diff --git a/src/i18n/index.ts b/src/i18n/index.ts
@@ -29,9 +29,25 @@ i18n.use(initReactI18next).init({
   },
 });
 
-// Save language changes to localStorage
+// Map an i18n language code to a valid BCP-47 tag for <html lang>. Screen
+// readers and search engines rely on this; the app defaults to zh-TW content,
+// so the document must not advertise itself as English.
+const toHtmlLang = (lng: string) => (lng === 'zh-TW' ? 'zh-Hant-TW' : lng);
+
+const applyHtmlLang = (lng: string) => {
+  if (typeof document !== 'undefined') {
+    document.documentElement.lang = toHtmlLang(lng);
+  }
+};
+
+// Sync on initial load (covers the case where the saved preference differs from
+// the static lang baked into index.html) and on every subsequent switch.
+applyHtmlLang(i18n.language);
+
+// Save language changes to localStorage and keep <html lang> in sync.
 i18n.on('languageChanged', (lng) => {
   localStorage.setItem('language-preference', lng);
+  applyHtmlLang(lng);
 });
 
 export default i18n;
diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json
@@ -75,7 +75,14 @@
   },
   "meta": {
     "title": "SIM Weekly Prayers Hub",
-    "description": "Weekly prayers for nations around the world"
+    "description": "Weekly prayers for nations around the world",
+    "titleSuffix": "SIM Taiwan",
+    "prayers": {
+      "description": "Browse weekly prayers that follow current world events — pray with us for the nations."
+    },
+    "familyPrayers": {
+      "description": "Family-friendly weekly prayers and World Kids News to pray for the nations together with your children."
+    }
   },
   "auth": {
     "welcome": "Welcome to SIM Prayer",
diff --git a/src/i18n/locales/zh-TW.json b/src/i18n/locales/zh-TW.json
@@ -86,7 +86,14 @@
   },
   "meta": {
     "title": "SIM 每週禱告中心",
-    "description": "為世界各國的每週禱告"
+    "description": "為世界各國的每週禱告",
+    "titleSuffix": "SIM 台灣",
+    "prayers": {
+      "description": "瀏覽每週禱告，跟著時事脈動，與我們同為世界萬國禱告。"
+    },
+    "familyPrayers": {
+      "description": "適合全家大小的每週禱告與世界兒童新聞，帶著孩子一起為萬國禱告。"
+    }
   },
   "auth": {
     "welcome": "歡迎來到 SIM 禱告",
diff --git a/src/index.css b/src/index.css
@@ -45,7 +45,8 @@ All colors MUST be HSL.
     --secondary-foreground: 215 25% 25%;
 
     --muted: 210 25% 96%;
-    --muted-foreground: 215 15% 55%;
+    /* Darkened from 215 15% 55% (~3.2:1) to meet WCAG AA 4.5:1 on --background. */
+    --muted-foreground: 215 18% 42%;
 
     --accent: 195 85% 88%;
     --accent-foreground: 215 25% 25%;
diff --git a/src/lib/seo.ts b/src/lib/seo.ts
@@ -0,0 +1,26 @@
+// Build a concise, plain-text meta description from prayer markdown content.
+// Strips markdown syntax (headings, emphasis, links, images, code) so search
+// engines and AI crawlers get clean snippet text, then truncates to a length
+// that fits within the typical search-result snippet.
+export function toMetaDescription(markdown: string, maxLength = 155): string {
+  const text = (markdown || '')
+    .replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+    .replace(/`([^`]*)`/g, '$1') // inline code
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ') // images
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links -> link text
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '') // ATX headings
+    .replace(/[*_~>#]/g, ' ') // residual markdown symbols
+    .replace(/\s+/g, ' ') // collapse whitespace
+    .trim();
+
+  // Slice by code points (Array.from), not UTF-16 units, so truncation never
+  // splits a surrogate pair (e.g. an emoji) into a broken trailing glyph.
+  const chars = Array.from(text);
+  if (chars.length <= maxLength) return text;
+  return (
+    chars
+      .slice(0, maxLength - 1)
+      .join('')
+      .trimEnd() + '…'
+  );
+}
diff --git a/src/pages/FamilyPrayerDetail.tsx b/src/pages/FamilyPrayerDetail.tsx
@@ -10,6 +10,8 @@ import { Label } from '@/components/ui/label';
 import { ArrowLeft, Calendar } from 'lucide-react';
 import WorldKidsNewsSlides from '@/components/WorldKidsNewsSlides';
 import SocialShareDropdown from '@/components/SocialShareDropdown';
+import SeoHead from '@/components/SeoHead';
+import { toMetaDescription } from '@/lib/seo';
 
 interface FamilyPrayer {
   id: string;
@@ -136,6 +138,7 @@ const FamilyPrayerDetail = () => {
   if (!familyPrayer) {
     return (
       <div className="min-h-screen bg-gradient-to-br from-background via-background to-accent/10 flex items-center justify-center">
+        <SeoHead title={t('prayer.noResults')} />
         <div className="text-center">
           <div className="text-muted-foreground mb-4">
             {t('prayer.noResults')}
@@ -157,6 +160,11 @@ const FamilyPrayerDetail = () => {
 
   return (
     <div className="min-h-screen bg-gradient-to-br from-background via-background to-accent/10">
+      <SeoHead
+        title={`${safeTitle} · ${formatDate(familyPrayer.week_date)}`}
+        description={toMetaDescription(translation?.content || '')}
+        image={familyPrayer.image_urls?.[0]}
+      />
       <div className="container mx-auto px-4 py-8">
         {/* Back Button */}
         <div className="mb-6 flex items-center justify-between">
diff --git a/src/pages/FamilyPrayers.tsx b/src/pages/FamilyPrayers.tsx
diff --git a/src/pages/Home.tsx b/src/pages/Home.tsx
diff --git a/src/pages/PrayerDetail.tsx b/src/pages/PrayerDetail.tsx
diff --git a/src/pages/Prayers.tsx b/src/pages/Prayers.tsx
