better_seo 0.14.0 → 1.0.0.1

data/docs/06_I18N_PAGE_GENERATOR.md

@@ -0,0 +1,233 @@
+# Step 06: Generatore Pagine i18n
+
+**Versione Target**: 0.7.0
+**Durata Stimata**: 1-2 settimane
+**Priorità**: 🟢 BASSA
+**Dipendenze**: Step 01, 02, 05
+
+---
+
+## Obiettivi
+
+1. ✅ Rails generator `rails g better_seo:page`
+2. ✅ File YAML per locale in config/locales/seo/:locale/
+3. ✅ Template per page types (website, article, product)
+4. ✅ Helper `set_seo_from_locale`
+5. ✅ Interpolazione variabili
+6. ✅ Rake task validazione traduzioni
+
+---
+
+## File da Creare
+
+```
+lib/generators/better_seo/page_generator.rb
+lib/generators/better_seo/page/templates/page_it.yml.tt
+lib/generators/better_seo/page/templates/page_en.yml.tt
+lib/better_seo/i18n/loader.rb
+lib/better_seo/tasks/i18n.rake
+```
+
+---
+
+## Implementazione: Page Generator
+
+```ruby
+# lib/generators/better_seo/page_generator.rb
+module BetterSeo
+  module Generators
+    class PageGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :type, type: :string, default: "website",
+        desc: "Type of page: website, article, product, organization"
+
+      class_option :locales, type: :array,
+        desc: "Locales to generate (default: from BetterSeo config)"
+
+      class_option :skip_twitter, type: :boolean, default: false
+      class_option :skip_open_graph, type: :boolean, default: false
+      class_option :skip_structured_data, type: :boolean, default: false
+
+      def create_locale_files
+        locales.each do |locale|
+          @locale = locale
+          @page_type = options[:type]
+
+          template_file = "page_#{locale}.yml"
+          output_path = "config/locales/seo/#{locale}/#{file_name}.yml"
+
+          template template_file, output_path
+        end
+      end
+
+      private
+
+      def locales
+        options[:locales] || BetterSeo.configuration.available_locales
+      end
+
+      def translations
+        # Template-specific translations
+        case @locale.to_sym
+        when :it
+          {
+            title: "Titolo Pagina",
+            description: "Descrizione per motori di ricerca",
+            keywords: ["parola1", "parola2"]
+          }
+        when :en
+          {
+            title: "Page Title",
+            description: "Description for search engines",
+            keywords: ["keyword1", "keyword2"]
+          }
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Template YAML
+
+```yaml
+# lib/generators/better_seo/page/templates/page_it.yml.tt
+it:
+  seo:
+    pages:
+      <%= file_name %>:
+        meta:
+          title: "<%= translations[:title] %>"
+          description: "<%= translations[:description] %>"
+          keywords: <%= translations[:keywords].to_yaml.sub("---\n", "") %>
+
+        <% unless options[:skip_open_graph] %>
+        open_graph:
+          title: "<%= translations[:title] %>"
+          description: "<%= translations[:description] %>"
+          type: "<%= @page_type %>"
+          image:
+            url: "https://example.com/images/og-<%= file_name %>-it.jpg"
+            width: 1200
+            height: 630
+        <% end %>
+
+        <% unless options[:skip_twitter] %>
+        twitter:
+          card: "summary_large_image"
+          title: "<%= translations[:title] %>"
+          description: "<%= translations[:description] %>"
+        <% end %>
+
+        <% unless options[:skip_structured_data] %>
+        structured_data:
+          type: "<%= structured_data_type %>"
+          data:
+            name: "<%= translations[:title] %>"
+        <% end %>
+```
+
+---
+
+## Helper set_seo_from_locale
+
+```ruby
+# Aggiunto a lib/better_seo/rails/concerns/seo_aware.rb
+
+def set_seo_from_locale(page_name, &block)
+  locale_key = "seo.pages.#{page_name}"
+
+  # Load from i18n
+  meta_data = I18n.t("#{locale_key}.meta", default: {})
+  og_data = I18n.t("#{locale_key}.open_graph", default: {})
+  sd_data = I18n.t("#{locale_key}.structured_data", default: {})
+
+  # Build SEO config
+  set_seo do |seo|
+    seo.merge!(meta_data)
+
+    # Open Graph
+    seo.open_graph do |og|
+      og.merge!(og_data)
+    end
+
+    # Structured Data
+    if sd_data[:type]
+      seo.structured_data sd_data[:type].underscore.to_sym do |sd|
+        sd.merge!(sd_data[:data] || {})
+      end
+    end
+  end
+
+  # Apply block overrides
+  yield(@_seo_builder) if block_given?
+end
+```
+
+---
+
+## Rake Task Validazione
+
+```ruby
+# lib/better_seo/tasks/i18n.rake
+namespace :better_seo do
+  namespace :i18n do
+    desc "Validate SEO translations across locales"
+    task validate: :environment do
+      locales = BetterSeo.configuration.available_locales
+      base_locale = locales.first
+
+      I18n.backend.load_translations
+
+      # Get all page keys from base locale
+      base_keys = I18n.t("seo.pages", locale: base_locale).keys
+
+      errors = []
+
+      base_keys.each do |page_key|
+        locales.each do |locale|
+          begin
+            page_data = I18n.t("seo.pages.#{page_key}", locale: locale)
+
+            # Check required keys
+            unless page_data.dig(:meta, :title)
+              errors << "Missing meta.title in #{locale}:seo.pages.#{page_key}"
+            end
+          rescue I18n::MissingTranslationData
+            errors << "Missing translation for #{locale}:seo.pages.#{page_key}"
+          end
+        end
+      end
+
+      if errors.any?
+        puts "✗ Validation failed:\n"
+        errors.each { |e| puts "  - #{e}" }
+        exit 1
+      else
+        puts "✓ All SEO translations validated successfully"
+      end
+    end
+  end
+end
+```
+
+---
+
+## Checklist
+
+- [ ] Page generator con templates
+- [ ] Template YAML per IT e EN
+- [ ] Support page types (website, article, product)
+- [ ] Options (--skip-twitter, --skip-open-graph, etc.)
+- [ ] Helper `set_seo_from_locale`
+- [ ] Interpolazione variabili (%{name})
+- [ ] Rake task `better_seo:i18n:validate`
+- [ ] Test generator output
+- [ ] Documentation esempi
+
+---
+
+**Prossimi Passi**: Step 07 - Image Optimization

data/docs/07_IMAGE_OPTIMIZATION.md

@@ -0,0 +1,260 @@
+# Step 07: Ottimizzazione Immagini e WebP
+
+**Versione Target**: 0.8.0
+**Durata Stimata**: 2-3 settimane
+**Priorità**: 🟢 BASSA (Nice to have)
+**Dipendenze**: Step 01, 05
+
+---
+
+## Obiettivi
+
+1. ✅ Conversione JPEG/PNG → WebP
+2. ✅ Resize automatico (varianti multiple)
+3. ✅ Compressione intelligente
+4. ✅ Helper `seo_image_tag` con lazy loading
+5. ✅ Picture tag con fallback
+6. ✅ Active Storage/CarrierWave/Shrine integration
+7. ✅ Rake tasks batch processing
+
+---
+
+## Dipendenze Esterne
+
+```ruby
+# better_seo.gemspec
+spec.add_dependency "image_processing", "~> 1.12"  # Wrapper per vips/imagemagick
+spec.add_dependency "ruby-vips", "~> 2.1"          # Per WebP e performance
+```
+
+**Sistema**: Richiede `libvips` installato
+
+```bash
+# macOS
+brew install vips
+
+# Ubuntu
+apt-get install libvips-dev
+
+# Check installation
+vips --version
+```
+
+---
+
+## File da Creare
+
+```
+lib/better_seo/images/optimizer.rb
+lib/better_seo/images/converter.rb
+lib/better_seo/images/resizer.rb
+lib/better_seo/images/compressor.rb
+lib/better_seo/images/validator.rb
+lib/better_seo/images/helpers/image_tag_helper.rb
+lib/better_seo/tasks/images.rake
+```
+
+---
+
+## Implementazione: WebP Converter
+
+```ruby
+# lib/better_seo/images/converter.rb
+require "image_processing/vips"
+
+module BetterSeo
+  module Images
+    class Converter
+      def self.to_webp(source_path, output_path = nil, quality: 80)
+        output_path ||= source_path.sub(/\.(jpe?g|png|gif)$/i, ".webp")
+
+        ImageProcessing::Vips
+          .source(source_path)
+          .convert("webp")
+          .saver(quality: quality)
+          .call(destination: output_path)
+
+        output_path
+      end
+    end
+  end
+end
+```
+
+---
+
+## Implementazione: Image Resizer
+
+```ruby
+# lib/better_seo/images/resizer.rb
+module BetterSeo
+  module Images
+    class Resizer
+      def initialize(source_path)
+        @source_path = source_path
+      end
+
+      def generate_variants(sizes_config)
+        variants = {}
+
+        sizes_config.each do |size_name, options|
+          output_path = variant_path(size_name)
+
+          pipeline = ImageProcessing::Vips.source(@source_path)
+
+          if options[:crop]
+            pipeline = pipeline.resize_to_fill(options[:width], options[:height])
+          else
+            pipeline = pipeline.resize_to_limit(options[:width], options[:height])
+          end
+
+          pipeline.call(destination: output_path)
+          variants[size_name] = output_path
+
+          # Generate WebP version
+          webp_path = Converter.to_webp(output_path)
+          variants["#{size_name}_webp".to_sym] = webp_path
+        end
+
+        variants
+      end
+
+      private
+
+      def variant_path(size_name)
+        ext = File.extname(@source_path)
+        base = @source_path.sub(ext, "")
+        "#{base}-#{size_name}#{ext}"
+      end
+    end
+  end
+end
+```
+
+---
+
+## Helper: seo_image_tag
+
+```ruby
+# lib/better_seo/images/helpers/image_tag_helper.rb
+module BetterSeo
+  module Images
+    module Helpers
+      module ImageTagHelper
+        def seo_image_tag(source, alt:, sizes: [], webp: true, lazy: false, **options)
+          if webp && sizes.any?
+            # Generate picture tag with WebP + responsive
+            render_picture_tag(source, alt: alt, sizes: sizes, lazy: lazy, **options)
+          elsif webp
+            # Simple picture tag with WebP fallback
+            render_simple_picture_tag(source, alt: alt, lazy: lazy, **options)
+          else
+            # Standard img tag
+            image_tag(source, alt: alt, loading: (lazy ? "lazy" : nil), **options)
+          end
+        end
+
+        private
+
+        def render_picture_tag(source, alt:, sizes:, lazy:, **options)
+          webp_srcset = sizes.map { |s| "#{variant_path(source, s, 'webp')} #{size_width(s)}w" }.join(", ")
+          jpg_srcset = sizes.map { |s| "#{variant_path(source, s, 'jpg')} #{size_width(s)}w" }.join(", ")
+
+          content_tag(:picture, class: "seo-image #{'lazy-image' if lazy}") do
+            concat tag(:source, type: "image/webp", srcset: webp_srcset)
+            concat tag(:source, type: "image/jpeg", srcset: jpg_srcset)
+            concat image_tag(source, alt: alt, loading: (lazy ? "lazy" : nil), **options)
+          end
+        end
+
+        def render_simple_picture_tag(source, alt:, lazy:, **options)
+          webp_source = source.sub(/\.(jpe?g|png)$/i, ".webp")
+
+          content_tag(:picture) do
+            concat tag(:source, type: "image/webp", srcset: webp_source)
+            concat image_tag(source, alt: alt, loading: (lazy ? "lazy" : nil), **options)
+          end
+        end
+
+        def variant_path(source, size, format)
+          ext = File.extname(source)
+          base = source.sub(ext, "")
+          "#{base}-#{size}.#{format}"
+        end
+
+        def size_width(size_name)
+          config = BetterSeo.configuration.images.sizes[size_name]
+          config&.dig(:width) || 1200
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Rake Tasks
+
+```ruby
+# lib/better_seo/tasks/images.rake
+namespace :better_seo do
+  namespace :images do
+    desc "Convert all images to WebP"
+    task :convert_to_webp, [:path] => :environment do |t, args|
+      path = args[:path] || Rails.root.join("public", "images")
+
+      Dir.glob("#{path}/**/*.{jpg,jpeg,png}").each do |file|
+        puts "Converting #{file}..."
+        BetterSeo::Images::Converter.to_webp(file)
+      end
+
+      puts "✓ WebP conversion completed"
+    end
+
+    desc "Generate image variants"
+    task :generate_variants, [:path] => :environment do |t, args|
+      path = args[:path] || Rails.root.join("public", "images")
+      sizes = BetterSeo.configuration.images.sizes
+
+      Dir.glob("#{path}/**/*.{jpg,jpeg,png}").each do |file|
+        puts "Generating variants for #{file}..."
+        resizer = BetterSeo::Images::Resizer.new(file)
+        resizer.generate_variants(sizes.to_h)
+      end
+
+      puts "✓ Image variants generated"
+    end
+
+    desc "Validate images for SEO"
+    task :validate => :environment do
+      # Implementation: check alt text, file sizes, etc.
+      puts "✓ Image validation completed"
+    end
+  end
+end
+```
+
+---
+
+## Checklist
+
+- [ ] WebP converter con ruby-vips
+- [ ] Image resizer per varianti
+- [ ] Smart compressor (quality optimization)
+- [ ] Helper `seo_image_tag`
+- [ ] Picture tag con srcset responsive
+- [ ] Lazy loading support
+- [ ] Blur placeholder (optional)
+- [ ] Active Storage integration
+- [ ] CarrierWave integration
+- [ ] Shrine integration
+- [ ] Rake tasks (convert, resize, validate)
+- [ ] Image validator (alt text, size, format)
+- [ ] Test coverage > 85%
+- [ ] Performance benchmarks
+
+---
+
+**Status**: Implementation Ready
+**Note**: Richiede libvips system dependency