feat: add markdown localization support with auto-sync option and enhanced rendering

Author: rsmithlal

app/helpers/better_together/markdown_helper.rb

@@ -57,5 +57,55 @@ def render_markdown_plain(source, options = {})
 
       MarkdownRendererService.new(source, options).render_plain_text
     end
+
+    # Renders markdown with automatic locale detection for file paths
+    #
+    # @param file [String, nil] Path to markdown file (with automatic locale detection)
+    # @param text [String, nil] Direct markdown text content
+    # @param locale [Symbol] Locale to use (defaults to current locale)
+    # @param options [Hash] Optional rendering options to pass to MarkdownRendererService
+    # @return [ActiveSupport::SafeBuffer] HTML-safe rendered markdown
+    #
+    # @example
+    #   <%= render_markdown_block(file: 'policies/privacy') %>
+    #   <%= render_markdown_block(text: t('content.welcome')) %>
+    def render_markdown_block(file: nil, text: nil, locale: I18n.locale, options: {})
+      I18n.with_locale(locale) do
+        content = if file.present?
+                    read_localized_file(file)
+                  else
+                    text
+                  end
+
+        render_markdown(content, options)
+      end
+    end
+
+    private
+
+    # Read a localized markdown file with automatic locale detection
+    #
+    # @param base_path [String] Base path to the markdown file (without locale extension)
+    # @return [String] File content or empty string if not found
+    def read_localized_file(base_path)
+      # Remove .md extension if present
+      base = base_path.sub(/\.(md|markdown)$/i, '')
+
+      # Try current locale, then fallback to English, then original
+      [
+        "#{base}.#{I18n.locale}.md",
+        "#{base}.en.md",
+        "#{base}.md"
+      ].each do |filename|
+        path = Rails.root.join('app', 'views', filename)
+        return File.read(path) if File.exist?(path)
+      end
+
+      Rails.logger.warn("Markdown file not found: #{base_path}")
+      ''
+    rescue Errno::ENOENT => e
+      Rails.logger.error("Failed to read localized markdown file: #{e.message}")
+      ''
+    end
   end
 end

app/models/better_together/content/markdown.rb

@@ -3,30 +3,44 @@
 module BetterTogether
   module Content
     # Renders markdown content from source or file
-    class Markdown < Block
+    class Markdown < Block # rubocop:disable Metrics/ClassLength
+      include Translatable
+
+      translates :markdown_source, type: :text
+
       store_attributes :content_data do
-        markdown_source String
         markdown_file_path String
+        auto_sync_from_file Boolean, default: false
       end
 
       validate :markdown_source_or_file_path_present
       validate :file_must_exist, if: :markdown_file_path?
       validate :file_must_be_markdown, if: :markdown_file_path?
 
+      # Load file content before validation if file path changed
+      before_validation :load_file_into_source,
+                        if: -> { markdown_file_path_changed? && auto_sync_from_file? }
+
       # Define permitted attributes for controller strong parameters
       def self.permitted_attributes
-        %i[markdown_source markdown_file_path]
+        %i[markdown_source markdown_file_path auto_sync_from_file]
       end
 
       # Get markdown content from either source or file
       def content
-        if markdown_source.present?
-          markdown_source
-        elsif markdown_file_path.present?
-          load_markdown_file
-        else
-          ''
-        end
+        return markdown_source if markdown_source.present? && !auto_sync_from_file?
+        return load_markdown_file_for_current_locale if markdown_file_path.present?
+
+        ''
+      end
+
+      # Manually import file content into markdown_source for all locales
+      def import_file_content!(sync_future_changes: false)
+        return false unless markdown_file_path.present?
+
+        load_localized_files
+        self.auto_sync_from_file = sync_future_changes
+        save!
       end
 
       # Render markdown content as HTML
@@ -47,8 +61,10 @@ def rendered_plain_text
       def as_indexed_json(_options = {})
         {
           id:,
-          localized_content: I18n.available_locales.index_with do |_locale|
-            rendered_plain_text
+          localized_content: I18n.available_locales.index_with do |locale|
+            I18n.with_locale(locale) do
+              rendered_plain_text
+            end
           end
         }
       end
@@ -61,6 +77,56 @@ def markdown_source_or_file_path_present
         errors.add(:base, 'Either markdown source or file path must be provided')
       end
 
+      def load_file_into_source
+        load_localized_files
+      end
+
+      def load_localized_files # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        base_path = markdown_file_path.sub(/\.(md|markdown)$/i, '')
+
+        I18n.available_locales.each do |locale|
+          load_locale_file(base_path, locale)
+        end
+      end
+
+      def load_locale_file(base_path, locale)
+        # Try locale-specific file first
+        locale_file = "#{base_path}.#{locale}.md"
+        resolved_path = resolve_file_path_for(locale_file)
+
+        if File.exist?(resolved_path)
+          set_markdown_for_locale(locale, resolved_path)
+        elsif locale == I18n.default_locale
+          load_default_file_for_locale(locale)
+        end
+      end
+
+      def set_markdown_for_locale(locale, file_path)
+        I18n.with_locale(locale) do
+          self.markdown_source = File.read(file_path)
+        end
+      end
+
+      def load_default_file_for_locale(locale)
+        default_path = resolve_file_path
+        return unless File.exist?(default_path)
+
+        set_markdown_for_locale(locale, default_path)
+      end
+
+      def load_markdown_file_for_current_locale
+        base_path = markdown_file_path.sub(/\.(md|markdown)$/i, '')
+        locale_file = "#{base_path}.#{I18n.locale}.md"
+
+        # Try locale-specific, fallback to default
+        [locale_file, markdown_file_path].each do |file|
+          path = resolve_file_path_for(file)
+          return File.read(path) if File.exist?(path)
+        end
+
+        ''
+      end
+
       def load_markdown_file
         file_path = resolve_file_path
         return '' unless File.exist?(file_path)
@@ -74,6 +140,12 @@ def resolve_file_path
         Rails.root.join(markdown_file_path)
       end
 
+      def resolve_file_path_for(path)
+        return Pathname.new(path) if Pathname.new(path).absolute?
+
+        Rails.root.join(path)
+      end
+
       def file_must_exist
         file_path = resolve_file_path
         return if File.exist?(file_path)

app/views/better_together/content/blocks/fields/_markdown.html.erb

@@ -9,7 +9,7 @@
      data-controller="better-together--markdown-block better-together--dependent-fields">
   <!-- Radio buttons to choose between source or file -->
   <div class="mb-3">
-    <%= label_tag nil, 'Markdown Source', class: 'form-label' %>
+    <%= label_tag nil, t('better_together.content.blocks.markdown.fields.markdown_source'), class: 'form-label' %>
     <div class="form-check">
       <%= radio_button_tag "#{scope}[markdown_source_type]", 'inline', inline_selected,
           class: 'form-check-input', 
@@ -19,7 +19,7 @@
             'better-together--markdown-block-target': 'sourceTypeRadio',
             'better-together--dependent-fields-target': 'controlField'
           } %>
-      <%= label_tag inline_radio_id, 'Write Markdown Inline', class: 'form-check-label' %>
+      <%= label_tag inline_radio_id, t('better_together.content.blocks.markdown.fields.write_inline'), class: 'form-check-label' %>
     </div>
     <div class="form-check">
       <%= radio_button_tag "#{scope}[markdown_source_type]", 'file', block.markdown_file_path.present?, 
@@ -30,33 +30,27 @@
             'better-together--markdown-block-target': 'sourceTypeRadio',
             'better-together--dependent-fields-target': 'controlField'
           } %>
-      <%= label_tag file_radio_id, 'Reference a Markdown File', class: 'form-check-label' %>
+      <%= label_tag file_radio_id, t('better_together.content.blocks.markdown.fields.reference_file'), class: 'form-check-label' %>
     </div>
   </div>
 
-  <!-- Inline markdown source textarea -->
+  <!-- Inline markdown source textarea with locale support -->
   <div class="mb-3 markdown-inline-field <%= 'hidden-field' unless inline_selected %>"
        data-better-together--markdown-block-target="inlineField"
        data-better-together--dependent-fields-target="dependentField"
        data-dependent-fields-control="<%= inline_radio_id %>"
        data-show-if-control_<%= inline_radio_id %>="inline">
-    <%= label_tag "#{scope}[markdown_source]", 'Markdown Content', class: 'form-label' %>
-    <%= text_area_tag "#{scope}[markdown_source]", 
-        block.markdown_source, 
-        class: "form-control font-monospace#{' is-invalid' if block.errors[:markdown_source].any?}", 
-        rows: 12,
-        placeholder: "# Your Markdown Here\n\nWrite your markdown content...",
-        data: { 'better-together--markdown-block-target': 'sourceTextarea' },
-        disabled: !inline_selected %>
 
-    <% if block.errors[:markdown_source].any? %>
-      <div class="invalid-feedback">
-        <%= block.errors[:markdown_source].join(", ") %>
-      </div>
-    <% end %>
+    <%= render partial: 'better_together/content/blocks/fields/shared/translatable_text_field',
+               locals: { 
+                 model: block, 
+                 scope: scope, 
+                 temp_id: temp_id, 
+                 attribute: 'markdown_source'
+               } %>
 
     <small class="form-text text-muted mt-2">
-      Write your markdown content directly. Supports GitHub-flavored markdown including tables, code blocks, and more.
+      <%= t('better_together.content.blocks.markdown.help.inline_content') %>
     </small>
   </div>
 
@@ -66,11 +60,11 @@
        data-better-together--dependent-fields-target="dependentField"
        data-dependent-fields-control="<%= file_radio_id %>"
        data-show-if-control_<%= file_radio_id %>="file">
-    <%= label_tag "#{scope}[markdown_file_path]", 'Markdown File Path', class: 'form-label' %>
+    <%= label_tag "#{scope}[markdown_file_path]", t('better_together.content.blocks.markdown.fields.file_path'), class: 'form-label' %>
     <%= text_field_tag "#{scope}[markdown_file_path]", 
         block.markdown_file_path, 
         class: "form-control font-monospace#{' is-invalid' if block.errors[:markdown_file_path].any?}", 
-        placeholder: "docs/README.md or /absolute/path/to/file.md",
+        placeholder: t('better_together.content.blocks.markdown.fields.file_path_placeholder'),
         data: { 'better-together--markdown-block-target': 'filePathInput' },
         disabled: inline_selected %>
 
@@ -81,18 +75,59 @@
     <% end %>
 
     <small class="form-text text-muted mt-2">
-      Path to a markdown file. Can be relative to Rails.root (e.g., <code>docs/README.md</code>) or absolute (e.g., <code>/path/to/file.md</code>). File must have a .md or .markdown extension.
+      <%= t('better_together.content.blocks.markdown.help.file_path') %>
+      <br>
+      <strong><%= t('better_together.content.blocks.markdown.help.localized_files') %></strong>
     </small>
+    
+    <!-- Auto-sync from file option -->
+    <div class="form-check mt-3">
+      <%= check_box_tag "#{scope}[auto_sync_from_file]",
+          '1',
+          block.auto_sync_from_file,
+          class: 'form-check-input',
+          id: "#{temp_id}_auto_sync",
+          disabled: inline_selected %>
+      <%= label_tag "#{temp_id}_auto_sync",
+          t('better_together.content.blocks.markdown.fields.auto_sync'),
+          class: 'form-check-label' %>
+      <small class="form-text text-muted d-block">
+        <%= t('better_together.content.blocks.markdown.help.auto_sync') %>
+      </small>
+    </div>
+    
+    <!-- Available translations indicator -->
+    <% if block.markdown_file_path.present? %>
+      <div class="alert alert-info mt-3 mb-0">
+        <strong><i class="fa fa-info-circle"></i> <%= t('better_together.content.blocks.markdown.help.available_translations') %></strong>
+        <% 
+          base_path = block.markdown_file_path.sub(/\.(md|markdown)$/i, '')
+          I18n.available_locales.each do |locale|
+            locale_file = "#{base_path}.#{locale}.md"
+            # Try to resolve the file path
+            file_path = if Pathname.new(locale_file).absolute?
+                         Pathname.new(locale_file)
+                       else
+                         Rails.root.join(locale_file)
+                       end
+            file_exists = File.exist?(file_path)
+        %>
+          <span class="badge <%= file_exists ? 'bg-success' : 'bg-secondary' %> me-1">
+            <%= locale.upcase %> <%= file_exists ? '✓' : '✗' %>
+          </span>
+        <% end %>
+      </div>
+    <% end %>
   </div>
 
   <!-- Preview area -->
   <div class="mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">
-      <%= label_tag nil, 'Preview', class: 'form-label mb-0' %>
+      <%= label_tag nil, t('better_together.content.blocks.markdown.fields.preview'), class: 'form-label mb-0' %>
       <button type="button" 
               class="btn btn-sm btn-outline-secondary"
               data-action="click->better-together--markdown-block#refreshPreview">
-        <i class="fa fa-refresh"></i> Refresh Preview
+        <i class="fa fa-refresh"></i> <%= t('better_together.content.blocks.markdown.fields.refresh_preview') %>
       </button>
     </div>
     <div class="border rounded p-3 bg-light markdown-content" 
@@ -102,7 +137,7 @@
         <%= block.rendered_html %>
       <% else %>
         <p class="text-muted mb-0">
-          <em>Preview will appear here...</em>
+          <em><%= t('better_together.content.blocks.markdown.help.preview_placeholder') %></em>
         </p>
       <% end %>
     </div>

config/locales/en.yml

@@ -722,6 +722,31 @@ en:
     content:
       blocks:
         associated_pages: Associated Pages
+        markdown:
+          fields:
+            auto_sync: Always load from file (ignore database content)
+            file_path: Markdown File Path
+            file_path_placeholder: docs/README.md or /absolute/path/to/file.md
+            markdown_source: Markdown Source
+            preview: Preview
+            reference_file: Reference a Markdown File
+            refresh_preview: Refresh Preview
+            write_inline: Write Markdown Inline
+          help:
+            auto_sync: When checked, content is always loaded from the file. When
+              unchecked, file content is imported into the database and can be edited
+              separately.
+            available_translations: 'Available translations:'
+            file_path: Path to a markdown file. Can be relative to Rails.root (e.g.,
+              docs/README.md) or absolute (e.g., /path/to/file.md). File must have
+              a .md or .markdown extension.
+            inline_content: Write your markdown content directly. Supports GitHub-flavored
+              markdown including tables, code blocks, and more. Content is translatable
+              for each locale.
+            localized_files: The system automatically looks for locale-specific versions
+              (e.g., privacy.en.md, privacy.es.md, privacy.fr.md) and falls back to
+              the base file if not found.
+            preview_placeholder: Preview will appear here...
     conversation_mailer:
       new_message_notification:
         from_address: New message via %{from_address}