@estation/create-cms-site 2.5.2 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estation/create-cms-site",
-  "version": "2.5.2",
+  "version": "2.7.0",
   "description": "MCP server to scaffold Next.js sites powered by eSTATION CMS",
   "type": "module",
   "bin": {

package/template/src/app/[locale]/[slug]/page.tsx

@@ -25,7 +25,7 @@ export default async function DynamicPage({ params }: PageProps) {
   const data = await getPageBySlug(slug, locale);
   const orderedBlocks = getOrderedBlocks(data.page.blocks, data.blocks);
 
-  return <SectionRenderer blocks={orderedBlocks} />;
+  return <SectionRenderer blocks={orderedBlocks} locale={locale} />;
 }
 
 function getOrderedBlocks(

package/template/src/app/[locale]/blog/[slug]/page.tsx

@@ -14,8 +14,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const block = findBlockBySlug(blocks, slug);
   if (!block) return { title: "Post Not Found" };
   return {
-    title: str(block.content.title, block.name),
-    description: str(block.content.excerpt),
+    title: str(block.content.title, locale, block.name),
+    description: str(block.content.excerpt, locale),
   };
 }
 
@@ -26,11 +26,11 @@ export default async function BlogDetailPage({ params }: PageProps) {
 
   if (!block) notFound();
 
-  const title = str(block.content.title, block.name);
-  const author = str(block.content.author);
-  const date = str(block.content.publishDate) || block.created_at;
-  const featuredImage = str(block.content.featuredImage);
-  const content = str(block.content.content);
+  const title = str(block.content.title, locale, block.name);
+  const author = str(block.content.author, locale);
+  const date = str(block.content.publishDate, locale) || block.created_at;
+  const featuredImage = str(block.content.featuredImage, locale);
+  const content = str(block.content.content, locale);
 
   return (
     <article className="py-16 px-6">

package/template/src/app/[locale]/blog/page.tsx

@@ -22,8 +22,8 @@ export default async function BlogListingPage({ params }: PageProps) {
   }
 
   const sorted = [...blocks].sort((a, b) => {
-    const da = str(a.content.publishDate) || a.created_at;
-    const db = str(b.content.publishDate) || b.created_at;
+    const da = str(a.content.publishDate, locale) || a.created_at;
+    const db = str(b.content.publishDate, locale) || b.created_at;
     return new Date(db).getTime() - new Date(da).getTime();
   });
 
@@ -36,11 +36,11 @@ export default async function BlogListingPage({ params }: PageProps) {
         ) : (
           <div className="space-y-8">
             {sorted.map((block) => {
-              const slug = str(block.content.slug);
-              const title = str(block.content.title, block.name);
-              const excerpt = str(block.content.excerpt);
-              const featuredImage = str(block.content.featuredImage);
-              const date = str(block.content.publishDate) || block.created_at;
+              const slug = str(block.content.slug, locale);
+              const title = str(block.content.title, locale, block.name);
+              const excerpt = str(block.content.excerpt, locale);
+              const featuredImage = str(block.content.featuredImage, locale);
+              const date = str(block.content.publishDate, locale) || block.created_at;
 
               return (
                 <article key={block.uuid} className="border-b pb-8">

package/template/src/app/[locale]/collections/[uuid]/page.tsx

@@ -20,7 +20,7 @@ export default async function CollectionPage({ params }: PageProps) {
         {blocks.length === 0 ? (
           <p className="text-gray-500 text-center">No items in this collection.</p>
         ) : (
-          <SectionRenderer blocks={blocks} />
+          <SectionRenderer blocks={blocks} locale={locale} />
         )}
       </div>
     </div>

package/template/src/app/[locale]/content/[typeName]/[slug]/page.tsx

@@ -0,0 +1,87 @@
+import { getContentBySlug } from "@/lib/cms-api";
+import { str } from "@/lib/types";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+
+interface PageProps {
+  params: Promise<{ locale: string; typeName: string; slug: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { typeName, slug, locale } = await params;
+  try {
+    const block = await getContentBySlug(typeName, slug);
+    return {
+      title: str(block.content?.title, locale, block.name),
+      description: str(block.content?.excerpt || block.content?.description, locale),
+    };
+  } catch {
+    return { title: typeName };
+  }
+}
+
+export default async function ContentDetailPage({ params }: PageProps) {
+  const { locale, typeName, slug } = await params;
+
+  let block;
+  try {
+    block = await getContentBySlug(typeName, slug);
+  } catch {
+    notFound();
+  }
+
+  if (!block) notFound();
+
+  const c = block.content || {};
+  const title = str(c.title, locale, block.name);
+  const image = str(c.featuredImage || c.image);
+  const body = str(c.content || c.body || c.description, locale);
+  const author = str(c.author, locale);
+  const date = str(c.publishDate || c.startDate) || block.created_at;
+
+  return (
+    <div className="py-16 px-6">
+      <div className="max-w-3xl mx-auto">
+        <a href={`/${locale}/content/${typeName}`} className="text-sm text-gray-500 hover:underline mb-6 block">
+          ← Back to {typeName}
+        </a>
+
+        {image && (
+          <img src={image} alt={title} className="w-full h-64 object-cover rounded-xl mb-8" />
+        )}
+
+        <h1 data-cms-field="title" className="text-4xl font-bold">{title}</h1>
+
+        {(author || date) && (
+          <p className="text-sm text-gray-500 mt-3">
+            {author && <span data-cms-field="author">By {author}</span>}
+            {author && date && " · "}
+            {date && <time>{new Date(date).toLocaleDateString()}</time>}
+          </p>
+        )}
+
+        {body && (
+          <div
+            data-cms-field="content"
+            className="prose prose-gray max-w-none mt-8"
+            dangerouslySetInnerHTML={{ __html: body }}
+          />
+        )}
+
+        {/* Render all other text fields */}
+        {Object.entries(c).map(([key, field]) => {
+          if (["title", "slug", "content", "body", "description", "featuredImage", "image", "author", "publishDate", "startDate", "status", "tags"].includes(key)) return null;
+          const val = str(field, locale);
+          if (!val) return null;
+          const label = key.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase());
+          return (
+            <div key={key} className="mt-6">
+              <h3 className="text-sm font-medium text-gray-500 uppercase">{label}</h3>
+              <p data-cms-field={key} className="mt-1">{val}</p>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/template/src/app/[locale]/content/[typeName]/page.tsx

@@ -0,0 +1,77 @@
+import { getContentByType } from "@/lib/cms-api";
+import { str } from "@/lib/types";
+import type { Metadata } from "next";
+
+interface PageProps {
+  params: Promise<{ locale: string; typeName: string }>;
+  searchParams: Promise<{ page?: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { typeName } = await params;
+  const label = typeName.charAt(0).toUpperCase() + typeName.slice(1);
+  return { title: label, description: `Browse ${label}` };
+}
+
+export default async function ContentListPage({ params, searchParams }: PageProps) {
+  const { locale, typeName } = await params;
+  const { page: pageParam } = await searchParams;
+  const page = parseInt(pageParam || "1", 10);
+
+  let result;
+  try {
+    result = await getContentByType(typeName, page, 20);
+  } catch {
+    result = { data: [], total: 0, page: 1, size: 20, total_pages: 0 };
+  }
+
+  const blocks = result.data || [];
+  const label = typeName.charAt(0).toUpperCase() + typeName.slice(1);
+
+  return (
+    <div className="py-16 px-6">
+      <div className="max-w-4xl mx-auto">
+        <h1 className="text-4xl font-bold mb-10">{label}</h1>
+        {blocks.length === 0 ? (
+          <p className="text-gray-500">No {typeName} content yet.</p>
+        ) : (
+          <div className="space-y-8">
+            {blocks.map((block) => {
+              const slug = str(block.content?.slug);
+              const title = str(block.content?.title, locale, block.name);
+              const excerpt = str(block.content?.excerpt || block.content?.description, locale);
+              const image = str(block.content?.featuredImage || block.content?.image);
+
+              return (
+                <article key={block.uuid} className="border-b pb-8">
+                  {image && (
+                    <img src={image} alt={title} className="w-full h-48 object-cover rounded-lg mb-4" />
+                  )}
+                  <h2 className="text-2xl font-semibold">
+                    {slug ? (
+                      <a href={`/${locale}/content/${typeName}/${slug}`} className="hover:underline">{title}</a>
+                    ) : title}
+                  </h2>
+                  {excerpt && <p className="text-gray-600 mt-2">{excerpt}</p>}
+                </article>
+              );
+            })}
+          </div>
+        )}
+
+        {/* Pagination */}
+        {result.total_pages > 1 && (
+          <div className="flex justify-center gap-2 mt-10">
+            {page > 1 && (
+              <a href={`/${locale}/content/${typeName}?page=${page - 1}`} className="px-4 py-2 border rounded hover:bg-gray-50">Previous</a>
+            )}
+            <span className="px-4 py-2 text-gray-500">Page {page} of {result.total_pages}</span>
+            {page < result.total_pages && (
+              <a href={`/${locale}/content/${typeName}?page=${page + 1}`} className="px-4 py-2 border rounded hover:bg-gray-50">Next</a>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/template/src/app/[locale]/events/[slug]/page.tsx

@@ -14,8 +14,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const block = findBlockBySlug(blocks, slug);
   if (!block) return { title: "Event Not Found" };
   return {
-    title: str(block.content.title, block.name),
-    description: str(block.content.description),
+    title: str(block.content.title, locale, block.name),
+    description: str(block.content.description, locale),
   };
 }
 
@@ -26,13 +26,13 @@ export default async function EventDetailPage({ params }: PageProps) {
 
   if (!block) notFound();
 
-  const title = str(block.content.title, block.name);
-  const description = str(block.content.description);
-  const location = str(block.content.location);
-  const startDate = str(block.content.startDate);
-  const endDate = str(block.content.endDate);
-  const organizer = str(block.content.organizer);
-  const content = str(block.content.content);
+  const title = str(block.content.title, locale, block.name);
+  const description = str(block.content.description, locale);
+  const location = str(block.content.location, locale);
+  const startDate = str(block.content.startDate, locale);
+  const endDate = str(block.content.endDate, locale);
+  const organizer = str(block.content.organizer, locale);
+  const content = str(block.content.content, locale);
 
   return (
     <article className="py-16 px-6">

package/template/src/app/[locale]/events/page.tsx

@@ -22,8 +22,8 @@ export default async function EventsListingPage({ params }: PageProps) {
   }
 
   const sorted = [...blocks].sort((a, b) => {
-    const da = str(a.content.startDate) || a.created_at;
-    const db = str(b.content.startDate) || b.created_at;
+    const da = str(a.content.startDate, locale) || a.created_at;
+    const db = str(b.content.startDate, locale) || b.created_at;
     return new Date(da).getTime() - new Date(db).getTime();
   });
 
@@ -36,12 +36,12 @@ export default async function EventsListingPage({ params }: PageProps) {
         ) : (
           <div className="space-y-8">
             {sorted.map((block) => {
-              const slug = str(block.content.slug);
-              const title = str(block.content.title, block.name);
-              const description = str(block.content.description);
-              const location = str(block.content.location);
-              const startDate = str(block.content.startDate);
-              const endDate = str(block.content.endDate);
+              const slug = str(block.content.slug, locale);
+              const title = str(block.content.title, locale, block.name);
+              const description = str(block.content.description, locale);
+              const location = str(block.content.location, locale);
+              const startDate = str(block.content.startDate, locale);
+              const endDate = str(block.content.endDate, locale);
 
               return (
                 <article key={block.uuid} className="border-b pb-8">

package/template/src/app/[locale]/news/[slug]/page.tsx

@@ -14,8 +14,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const block = findBlockBySlug(blocks, slug);
   if (!block) return { title: "Article Not Found" };
   return {
-    title: str(block.content.title, block.name),
-    description: str(block.content.excerpt),
+    title: str(block.content.title, locale, block.name),
+    description: str(block.content.excerpt, locale),
   };
 }
 
@@ -26,12 +26,12 @@ export default async function NewsDetailPage({ params }: PageProps) {
 
   if (!block) notFound();
 
-  const title = str(block.content.title, block.name);
-  const author = str(block.content.author);
-  const category = str(block.content.category);
-  const date = str(block.content.publishDate) || block.created_at;
-  const featuredImage = str(block.content.featuredImage);
-  const content = str(block.content.content);
+  const title = str(block.content.title, locale, block.name);
+  const author = str(block.content.author, locale);
+  const category = str(block.content.category, locale);
+  const date = str(block.content.publishDate, locale) || block.created_at;
+  const featuredImage = str(block.content.featuredImage, locale);
+  const content = str(block.content.content, locale);
 
   return (
     <article className="py-16 px-6">

package/template/src/app/[locale]/news/page.tsx

@@ -22,8 +22,8 @@ export default async function NewsListingPage({ params }: PageProps) {
   }
 
   const sorted = [...blocks].sort((a, b) => {
-    const da = str(a.content.publishDate) || a.created_at;
-    const db = str(b.content.publishDate) || b.created_at;
+    const da = str(a.content.publishDate, locale) || a.created_at;
+    const db = str(b.content.publishDate, locale) || b.created_at;
     return new Date(db).getTime() - new Date(da).getTime();
   });
 
@@ -36,11 +36,11 @@ export default async function NewsListingPage({ params }: PageProps) {
         ) : (
           <div className="space-y-8">
             {sorted.map((block) => {
-              const slug = str(block.content.slug);
-              const title = str(block.content.title, block.name);
-              const excerpt = str(block.content.excerpt);
-              const category = str(block.content.category);
-              const date = str(block.content.publishDate) || block.created_at;
+              const slug = str(block.content.slug, locale);
+              const title = str(block.content.title, locale, block.name);
+              const excerpt = str(block.content.excerpt, locale);
+              const category = str(block.content.category, locale);
+              const date = str(block.content.publishDate, locale) || block.created_at;
 
               return (
                 <article key={block.uuid} className="border-b pb-8">

package/template/src/app/[locale]/page.tsx

@@ -25,7 +25,7 @@ export default async function Home({ params }: PageProps) {
   try {
     const data = await getPageBySlug("index", locale);
     const orderedBlocks = getOrderedBlocks(data.page.blocks, data.blocks);
-    return <SectionRenderer blocks={orderedBlocks} />;
+    return <SectionRenderer blocks={orderedBlocks} locale={locale} />;
   } catch {
     return (
       <div className="py-20 px-6 text-center">

package/template/src/components/SectionRenderer.tsx

@@ -26,7 +26,7 @@ const SECTION_MAP: Record<string, React.FC<SectionProps>> = {
   form: ContactSection,
 };
 
-export function SectionRenderer({ blocks }: { blocks: ContentBlock[] }) {
+export function SectionRenderer({ blocks, locale }: { blocks: ContentBlock[]; locale?: string }) {
   return (
     <>
       {blocks.map((block) => {
@@ -34,7 +34,7 @@ export function SectionRenderer({ blocks }: { blocks: ContentBlock[] }) {
         const Component = SECTION_MAP[tag] || GenericSection;
         return (
           <section key={block.uuid} data-cms-block={tag}>
-            <Component block={block} />
+            <Component block={block} locale={locale} />
           </section>
         );
       })}

package/template/src/components/sections/CTASection.tsx

@@ -1,16 +1,16 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function CTASection({ block }: SectionProps) {
+export function CTASection({ block, locale }: SectionProps) {
   const c = block.content;
-  const description = str(c.description);
-  const buttonText = str(c.buttonText);
+  const description = str(c.description, locale);
+  const buttonText = str(c.buttonText, locale);
 
   return (
     <div className="py-20 px-6 bg-gray-900 text-white text-center">
       <div className="max-w-2xl mx-auto">
         <h2 data-cms-field="title" className="text-3xl font-bold mb-4">
-          {str(c.title, "Ready to get started?")}
+          {str(c.title, locale, "Ready to get started?")}
         </h2>
         {description && (
           <p data-cms-field="description" className="text-lg text-gray-300 mb-8">
@@ -20,7 +20,7 @@ export function CTASection({ block }: SectionProps) {
         {buttonText && (
           <a
             data-cms-field="buttonText"
-            href={str(c.buttonLink, "#")}
+            href={str(c.buttonLink, locale, "#")}
             className="inline-block px-8 py-3 bg-white text-gray-900 rounded-lg font-medium hover:bg-gray-100 transition-colors"
           >
             {buttonText}

package/template/src/components/sections/ContactSection.tsx

@@ -1,13 +1,13 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function ContactSection({ block }: SectionProps) {
+export function ContactSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title, "Contact Us");
-  const description = str(c.description);
-  const email = str(c.email);
-  const phone = str(c.phone);
-  const address = str(c.address);
+  const title = str(c.title, locale, "Contact Us");
+  const description = str(c.description, locale);
+  const email = str(c.email, locale);
+  const phone = str(c.phone, locale);
+  const address = str(c.address, locale);
 
   return (
     <div className="py-16 px-6">

package/template/src/components/sections/FAQSection.tsx

@@ -1,9 +1,9 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function FAQSection({ block }: SectionProps) {
+export function FAQSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title);
+  const title = str(c.title, locale);
 
   const faqs: { question: string; answer: string }[] = [];
   if (Array.isArray(c.items?.fieldValue)) {

package/template/src/components/sections/FeaturesSection.tsx

@@ -1,10 +1,10 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function FeaturesSection({ block }: SectionProps) {
+export function FeaturesSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title);
-  const description = str(c.description);
+  const title = str(c.title, locale);
+  const description = str(c.description, locale);
 
   const features: { title: string; description: string }[] = [];
   if (Array.isArray(c.items?.fieldValue)) {

package/template/src/components/sections/GallerySection.tsx

@@ -1,9 +1,9 @@
 import type { SectionProps, ListItem } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function GallerySection({ block }: SectionProps) {
+export function GallerySection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title);
+  const title = str(c.title, locale);
   const items = (Array.isArray(c.items?.fieldValue) ? c.items.fieldValue : []) as ListItem[];
 
   return (

package/template/src/components/sections/GenericSection.tsx

@@ -1,6 +1,6 @@
 import type { SectionProps } from "@/lib/types";
 
-export function GenericSection({ block }: SectionProps) {
+export function GenericSection({ block, locale }: SectionProps) {
   const c = block.content;
   const entries = Object.entries(c).filter(
     ([, field]) => field?.fieldValue !== undefined && field?.fieldValue !== null && field?.fieldValue !== ""

package/template/src/components/sections/HeroSection.tsx

@@ -1,17 +1,17 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function HeroSection({ block }: SectionProps) {
+export function HeroSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const buttonText = str(c.buttonText);
+  const buttonText = str(c.buttonText, locale);
 
   return (
     <div className="py-20 px-6 text-center">
       <h1 data-cms-field="header" className="text-4xl md:text-5xl font-bold tracking-tight">
-        {str(c.header, "Hero Title")}
+        {str(c.header, locale, "Hero Title")}
       </h1>
       <p data-cms-field="description" className="mt-4 text-lg text-gray-600 max-w-2xl mx-auto">
-        {str(c.description, "Hero description goes here.")}
+        {str(c.description, locale, "Hero description goes here.")}
       </p>
       {buttonText && (
         <a

package/template/src/components/sections/SliderSection.tsx

@@ -4,7 +4,7 @@ import { useState } from "react";
 import type { SectionProps, ListItem } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function SliderSection({ block }: SectionProps) {
+export function SliderSection({ block, locale }: SectionProps) {
   const c = block.content;
   const items = (Array.isArray(c.items?.fieldValue) ? c.items.fieldValue : []) as ListItem[];
   const [current, setCurrent] = useState(0);

package/template/src/components/sections/TestimonialsSection.tsx

@@ -1,9 +1,9 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function TestimonialsSection({ block }: SectionProps) {
+export function TestimonialsSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title);
+  const title = str(c.title, locale);
 
   const testimonials: { name: string; quote: string; role?: string }[] = [];
   if (Array.isArray(c.items?.fieldValue)) {

package/template/src/components/sections/TextSection.tsx

@@ -1,11 +1,11 @@
 import type { SectionProps } from "@/lib/types";
 import { str } from "@/lib/types";
 
-export function TextSection({ block }: SectionProps) {
+export function TextSection({ block, locale }: SectionProps) {
   const c = block.content;
-  const title = str(c.title);
-  const subtitle = str(c.subtitle);
-  const body = str(c.body);
+  const title = str(c.title, locale);
+  const subtitle = str(c.subtitle, locale);
+  const body = str(c.body, locale);
 
   return (
     <div className="py-16 px-6 max-w-3xl mx-auto">

package/template/src/lib/cms-api.ts

@@ -93,6 +93,53 @@ export async function getCollections(): Promise<Collection[]> {
   return cmsFetch<Collection[]>("/public/content/collections", ["collections"]);
 }
 
+// ── v2 API functions ──────────────────────────────────────────────
+
+const CMS_V2_URL = CMS_API_URL.replace("/api/v1", "/api/v2");
+
+async function cmsV2Fetch<T>(path: string, tags?: string[]): Promise<T> {
+  const url = `${CMS_V2_URL}${path}`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10000);
+  const res = await fetch(url, {
+    headers: { "X-API-TOKEN": CMS_API_TOKEN },
+    signal: controller.signal,
+    next: { revalidate: 60, tags: tags || [] },
+  });
+  clearTimeout(timeout);
+  if (!res.ok) throw new Error(`CMS v2 API error: ${res.status} for ${path}`);
+  const json = await res.json();
+  return json.data ?? json;
+}
+
+/** List content items of a specific type (paginated). */
+export async function getContentByType(
+  typeName: string,
+  page = 1,
+  size = 20,
+  filters?: Record<string, string>
+): Promise<PaginatedResponse<ContentBlock>> {
+  const params = new URLSearchParams({ page: String(page), size: String(size) });
+  if (filters) {
+    for (const [k, v] of Object.entries(filters)) params.set(`filter.${k}`, v);
+  }
+  return cmsV2Fetch<PaginatedResponse<ContentBlock>>(
+    `/public/content/${encodeURIComponent(typeName)}?${params}`,
+    [`content-${typeName}`]
+  );
+}
+
+/** Get a single content item by its slug. */
+export async function getContentBySlug(
+  typeName: string,
+  slug: string
+): Promise<ContentBlock> {
+  return cmsV2Fetch<ContentBlock>(
+    `/public/content/${encodeURIComponent(typeName)}/slug/${encodeURIComponent(slug)}`,
+    [`content-${typeName}-${slug}`]
+  );
+}
+
 export async function searchContent(
   query: string,
   type?: string,

package/template/src/lib/types.ts

@@ -1,12 +1,43 @@
 export interface ContentField {
   fieldType: string;
-  fieldValue: string | ListItem[];
+  fieldValue: string | Record<string, string> | ListItem[];
 }
 
-/** Safely extract a string value from a content field. */
-export function str(field: ContentField | undefined, fallback = ""): string {
-  if (!field || typeof field.fieldValue !== "string") return fallback;
-  return field.fieldValue || fallback;
+// Known locale codes for detecting locale vs fallback string
+const LOCALE_CODE_SET = new Set(["en","es","fr","de","zh","ja","ko","pt","ar","ku","tr","it","ru","hi","fa","he","ur","nl","sv","pl","th","vi","id","ms","fil","bn","ta","te","ml","kn"]);
+
+/**
+ * Safely extract a string value from a content field.
+ * Handles both plain strings and multilingual locale maps.
+ *
+ * Usage:
+ *   str(field)                      → returns default locale value
+ *   str(field, "en")                → returns English value
+ *   str(field, "ar")                → returns Arabic value
+ *   str(field, "ar", "fallback")    → returns Arabic or "fallback"
+ *   str(field, "Fallback Text")     → returns value or "Fallback Text" (backwards compat)
+ */
+export function str(field: ContentField | undefined, localeOrFallback?: string, fallback = ""): string {
+  if (!field) return fallback || localeOrFallback || "";
+
+  const fv = field.fieldValue;
+
+  // Determine if second arg is a locale code or a fallback string
+  const isLocale = localeOrFallback ? LOCALE_CODE_SET.has(localeOrFallback) : false;
+  const locale = isLocale ? localeOrFallback : undefined;
+  const fb = isLocale ? fallback : (localeOrFallback || fallback);
+
+  // Plain string (old format or non-translatable field)
+  if (typeof fv === "string") return fv || fb;
+
+  // Multilingual locale map: { en: "Hello", ar: "مرحبا" }
+  if (fv && typeof fv === "object" && !Array.isArray(fv)) {
+    const localeMap = fv as Record<string, string>;
+    if (locale && localeMap[locale]) return localeMap[locale];
+    return localeMap["en"] || Object.values(localeMap)[0] || fb;
+  }
+
+  return fb;
 }
 
 /** Safely extract a list value from a content field. */
@@ -94,6 +125,7 @@ export interface PageWithBlocksResponse {
 
 export interface SectionProps {
   block: ContentBlock;
+  locale?: string;
   className?: string;
 }