Add localized page metadata endpoint with comprehensive SEO support

Author: etewiah

app/controllers/api_public/v1/localized_pages_controller.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    # Returns comprehensive localized page metadata for SEO and rendering
+    #
+    # This endpoint provides all data needed to render a page in a specific locale,
+    # including SEO meta tags, Open Graph, Twitter Cards, JSON-LD structured data,
+    # navigation info, and rendered page content.
+    #
+    # All text fields (title, meta_description, meta_keywords) are automatically
+    # returned in the requested locale via Mobility translations.
+    #
+    class LocalizedPagesController < BaseController
+      include ApiPublic::Cacheable
+      include UrlLocalizationHelper
+
+      def show
+        setup_locale
+
+        unless website_provisioned?
+          render json: website_not_provisioned_error, status: :not_found
+          return
+        end
+
+        page = Pwb::Current.website.pages.find_by(slug: params[:page_slug])
+
+        unless page
+          render json: page_not_found_error, status: :not_found
+          return
+        end
+
+        set_short_cache(max_age: 1.hour, etag_data: [page.id, page.updated_at, I18n.locale])
+        return if performed?
+
+        render json: build_localized_page_response(page)
+      end
+
+      private
+
+      def setup_locale
+        locale = params[:locale] || I18n.default_locale
+        I18n.locale = locale.to_sym
+      end
+
+      def website_provisioned?
+        Pwb::Current.website.present? && Pwb::Current.website.pages.exists?
+      end
+
+      def website_not_provisioned_error
+        {
+          error: "Website not provisioned",
+          message: "The website has not been provisioned with any pages.",
+          code: "WEBSITE_NOT_PROVISIONED"
+        }
+      end
+
+      def page_not_found_error
+        {
+          error: "Page not found",
+          code: "PAGE_NOT_FOUND"
+        }
+      end
+
+      def build_localized_page_response(page)
+        website = Pwb::Current.website
+
+        {
+          id: page.id,
+          slug: page.slug,
+          # Mobility-translated fields - automatically return current locale's value
+          title: page.seo_title.presence || page.page_title.presence || page.slug.titleize,
+          meta_description: page.meta_description,
+          meta_keywords: page.meta_keywords,
+          # Canonical URL is generated dynamically based on locale
+          canonical_url: build_canonical_url(page),
+          last_modified: page.updated_at.iso8601,
+          etag: generate_page_etag(page),
+          cache_control: "public, max-age=3600",
+          og: build_open_graph(page, website),
+          twitter: build_twitter_card(page, website),
+          json_ld: build_json_ld(page, website),
+          breadcrumbs: build_breadcrumbs(page),
+          alternate_locales: build_alternate_locales(page),
+          html_elements: build_html_elements(page),
+          sort_order_top_nav: page.sort_order_top_nav,
+          show_in_top_nav: page.show_in_top_nav,
+          sort_order_footer: page.sort_order_footer,
+          show_in_footer: page.show_in_footer,
+          visible: page.visible,
+          page_contents: build_page_contents(page)
+        }
+      end
+
+      def generate_page_etag(page)
+        "\"#{Digest::MD5.hexdigest("#{page.id}-#{page.updated_at}-#{I18n.locale}")}\""
+      end
+
+      def build_canonical_url(page)
+        host = request.host_with_port
+        protocol = request.protocol
+        path = build_page_path(page, I18n.locale)
+
+        "#{protocol}#{host}#{path}"
+      end
+
+      def build_page_path(page, locale)
+        default_locale = default_website_locale
+
+        if locale.to_s == default_locale.to_s
+          "/p/#{page.slug}"
+        else
+          "/#{locale}/p/#{page.slug}"
+        end
+      end
+
+      def default_website_locale
+        Pwb::Current.website&.default_client_locale&.to_s || "en"
+      end
+
+      def build_open_graph(page, website)
+        site_name = website.company_display_name.presence ||
+                    website.agency&.display_name.presence ||
+                    "Property Website"
+
+        og = {
+          "og:title" => page.seo_title.presence || page.page_title.presence || page.slug.titleize,
+          "og:description" => page.meta_description.presence || website_default_description(website),
+          "og:type" => "website",
+          "og:url" => build_canonical_url(page),
+          "og:site_name" => site_name
+        }
+
+        # Add og:image if available from page or website
+        og_image = page_og_image(page) || website_logo(website)
+        og["og:image"] = og_image if og_image.present?
+
+        og.compact
+      end
+
+      def build_twitter_card(page, website)
+        {
+          "twitter:card" => "summary_large_image",
+          "twitter:title" => page.seo_title.presence || page.page_title.presence || page.slug.titleize,
+          "twitter:description" => page.meta_description.presence || website_default_description(website),
+          "twitter:image" => page_og_image(page) || website_logo(website)
+        }.compact
+      end
+
+      def build_json_ld(page, website)
+        site_name = website.company_display_name.presence ||
+                    website.agency&.display_name.presence ||
+                    "Property Website"
+
+        json_ld = {
+          "@context" => "https://schema.org",
+          "@type" => "WebPage",
+          "name" => page.seo_title.presence || page.page_title.presence || page.slug.titleize,
+          "description" => page.meta_description,
+          "url" => build_canonical_url(page),
+          "inLanguage" => I18n.locale.to_s,
+          "datePublished" => page.created_at&.to_date&.iso8601,
+          "dateModified" => page.updated_at&.to_date&.iso8601,
+          "publisher" => build_publisher_json_ld(site_name, website)
+        }
+
+        json_ld.compact
+      end
+
+      def build_publisher_json_ld(site_name, website)
+        publisher = {
+          "@type" => "Organization",
+          "name" => site_name
+        }
+
+        logo_url = website_logo(website)
+        if logo_url.present?
+          publisher["logo"] = {
+            "@type" => "ImageObject",
+            "url" => logo_url
+          }
+        end
+
+        publisher
+      end
+
+      def build_breadcrumbs(page)
+        locale = I18n.locale
+        default_locale = default_website_locale
+
+        home_url = locale.to_s == default_locale ? "/" : "/#{locale}/"
+        page_url = build_page_path(page, locale)
+
+        [
+          { "name" => I18n.t("breadcrumbs.home", default: "Home"), "url" => home_url },
+          { "name" => page.page_title.presence || page.slug.titleize, "url" => page_url }
+        ]
+      end
+
+      def build_alternate_locales(page)
+        website = Pwb::Current.website
+        supported_locales = website.supported_locales || [default_website_locale]
+        current_base_locale = normalize_locale_for_mobility(I18n.locale)&.to_s
+
+        supported_locales.filter_map do |locale|
+          # Normalize for comparison to handle "es" vs "es-MX"
+          locale_base = normalize_locale_for_mobility(locale)&.to_s
+          next if locale_base == current_base_locale
+
+          # Use the base locale for the URL path
+          path = build_page_path(page, locale_base || locale)
+          url = "#{request.protocol}#{request.host_with_port}#{path}"
+
+          { "locale" => locale_base || locale.to_s, "url" => url }
+        end
+      end
+
+      def build_html_elements(page)
+        # Return localized UI element labels for the page
+        # These can be used by frontend frameworks that need pre-translated strings
+        elements = []
+
+        # Page title element
+        elements << {
+          "element_class_id" => "page_title",
+          "element_label" => build_element_translations(:page_title, page)
+        }
+
+        # Common form elements (if page has forms)
+        elements << {
+          "element_class_id" => "submit_button",
+          "element_label" => build_i18n_translations("buttons.submit", "Submit")
+        }
+
+        elements << {
+          "element_class_id" => "back_button",
+          "element_label" => build_i18n_translations("buttons.back", "Back")
+        }
+
+        elements
+      end
+
+      def build_element_translations(attribute, page)
+        translations = {}
+        supported_locales = website_supported_locales
+
+        supported_locales.each do |locale|
+          # Normalize locale for Mobility (e.g., "en-US" → "en")
+          mobility_locale = normalize_locale_for_mobility(locale)
+          next unless mobility_locale
+
+          Mobility.with_locale(mobility_locale) do
+            value = page.send(attribute)
+            translations[locale.to_s] = value if value.present?
+          end
+        end
+
+        # Fallback to slug if no translations
+        translations[I18n.default_locale.to_s] ||= page.slug.titleize if translations.empty?
+
+        translations
+      end
+
+      def build_i18n_translations(key, default)
+        translations = {}
+        supported_locales = website_supported_locales
+
+        supported_locales.each do |locale|
+          # Use the full locale for I18n if available, otherwise use normalized
+          i18n_locale = I18n.available_locales.map(&:to_s).include?(locale.to_s) ? locale : normalize_locale_for_mobility(locale)
+          next unless i18n_locale
+
+          translations[locale.to_s] = I18n.t(key, locale: i18n_locale, default: default)
+        end
+
+        translations
+      end
+
+      # Get website's supported locales
+      def website_supported_locales
+        Pwb::Current.website&.supported_locales || I18n.available_locales.map(&:to_s)
+      end
+
+      # Normalize regional locale codes to base codes for Mobility
+      # e.g., "en-US" → :en, "es-MX" → :es
+      def normalize_locale_for_mobility(locale)
+        return nil if locale.blank?
+
+        base_locale = locale.to_s.split('-').first.to_sym
+        # Only return if it's a valid Mobility/I18n locale
+        I18n.available_locales.include?(base_locale) ? base_locale : nil
+      end
+
+      def build_page_contents(page)
+        return [] unless page.respond_to?(:ordered_visible_page_contents)
+
+        page.ordered_visible_page_contents.map do |page_content|
+          raw_html = page_content.is_rails_part ? nil : page_content.content&.raw
+          localized_html = raw_html.present? ? localize_html_urls(raw_html) : nil
+
+          {
+            "page_part_key" => page_content.page_part_key,
+            "sort_order" => page_content.sort_order,
+            "visible" => page_content.visible_on_page,
+            "is_rails_part" => page_content.is_rails_part || false,
+            "rendered_html" => localized_html,
+            "label" => page_content.label
+          }
+        end
+      end
+
+      # Helper methods for website data
+
+      def website_default_description(website)
+        website.default_meta_description.presence || "Find your dream property"
+      end
+
+      def website_logo(website)
+        return nil unless website.respond_to?(:logo_url)
+        website.logo_url.presence
+      end
+
+      def page_og_image(page)
+        # Check if page has a custom OG image in its details or translations
+        return nil unless page.respond_to?(:details) && page.details.is_a?(Hash)
+        page.details["og_image_url"].presence
+      end
+    end
+  end
+end

app/models/pwb/page.rb

@@ -47,7 +47,9 @@ class Page < ApplicationRecord
     belongs_to :website, class_name: 'Pwb::Website', optional: true
 
     # Mobility translations with container backend (single JSONB column)
-    translates :raw_html, :page_title, :link_title
+    # SEO fields are localized for proper multilingual SEO support
+    translates :raw_html, :page_title, :link_title,
+               :seo_title, :meta_description, :meta_keywords
 
     has_many :links, class_name: 'Pwb::Link', foreign_key: 'page_slug', primary_key: 'slug'
     has_one :main_link, -> { where(placement: :top_nav) }, foreign_key: 'page_slug', primary_key: 'slug', class_name: 'Pwb::Link'

config/routes.rb

@@ -752,6 +752,10 @@
         get "/pages/:id" => "pages#show"
         get "/pages/by_slug/:slug" => "pages#show_by_slug"
 
+        # Localized page with comprehensive SEO metadata
+        # Returns full page data including OG tags, JSON-LD, translations, etc.
+        get "/localized_page/by_slug/:page_slug" => "localized_pages#show"
+
         # Translations
         get "/translations" => "translations#index"