data_porter 2.0.0 → 2.1.1

data/lib/generators/data_porter/locale/locale_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module DataPorter
+  module Generators
+    class LocaleGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../config/locales", __dir__)
+
+      argument :locale, type: :string, default: "en"
+
+      def copy_locale_file
+        source = source_file
+        destination = "config/locales/data_porter.#{locale}.yml"
+
+        copy_file(source, destination)
+        gsub_file(destination, /^#{source_locale}:/, "#{locale}:") unless locale == source_locale
+      end
+
+      def show_instructions
+        say ""
+        say "DataPorter locale file created: config/locales/data_porter.#{locale}.yml", :green
+        say ""
+        say "Next steps:"
+        say "  1. Translate the values in the generated file"
+        say "  2. Set your default locale in config/application.rb:"
+        say "       config.i18n.default_locale = :#{locale}"
+        say ""
+      end
+
+      private
+
+      def source_file
+        File.exist?(File.join(self.class.source_root, "#{locale}.yml")) ? "#{locale}.yml" : "en.yml"
+      end
+
+      def source_locale
+        source_file.delete_suffix(".yml")
+      end
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,98 @@
+site_name: DataPorter
+site_description: A mountable Rails engine for data import workflows
+site_url: https://seryllns.github.io/data_porter
+repo_url: https://github.com/SerylLns/data_porter
+repo_name: SerylLns/data_porter
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Inter
+    code: JetBrains Mono
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/database-import
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - navigation.indexes
+    - navigation.footer
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - toc.follow
+
+plugins:
+  - search
+  - exclude:
+      glob:
+        - blog/*
+        - blog_part_2/*
+        - V1_PLAN.md
+        - dev_to.md
+        - reddit_post.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.snippets:
+      base_path: ["."]
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/SerylLns/data_porter
+    - icon: fontawesome/brands/dev
+      link: https://dev.to/seryllns
+  generator: false
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Reference:
+      - Configuration: CONFIGURATION.md
+      - Targets: TARGETS.md
+      - Sources: SOURCES.md
+      - Column Mapping: MAPPING.md
+      - Routes: routes.md
+  - Roadmap: ROADMAP.md
+  - Changelog: changelog.md
+  - Contributing: contributing.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_porter
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Seryl Lounis
@@ -139,7 +139,8 @@ files:
 - app/views/data_porter/mapping_templates/index.html.erb
 - app/views/data_porter/mapping_templates/new.html.erb
 - app/views/layouts/data_porter/application.html.erb
-- bookmarklet.md
+- config/locales/en.yml
+- config/locales/fr.yml
 - config/routes.rb
 - lib/data_porter.rb
 - lib/data_porter/broadcaster.rb
@@ -183,9 +184,11 @@ files:
 - lib/generators/data_porter/install/templates/create_data_porter_imports.rb.erb
 - lib/generators/data_porter/install/templates/create_data_porter_mapping_templates.rb.erb
 - lib/generators/data_porter/install/templates/initializer.rb
+- lib/generators/data_porter/locale/locale_generator.rb
 - lib/generators/data_porter/target/target_generator.rb
 - lib/generators/data_porter/target/templates/target.rb.tt
 - lib/tasks/data_porter.rake
+- mkdocs.yml
 - sig/data_porter.rbs
 homepage: https://github.com/SerylLns/data_porter
 licenses:
@@ -194,7 +197,7 @@ metadata:
   homepage_uri: https://github.com/SerylLns/data_porter
   source_code_uri: https://github.com/SerylLns/data_porter
   changelog_uri: https://github.com/SerylLns/data_porter/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/SerylLns/data_porter#readme
+  documentation_uri: https://seryllns.github.io/data_porter/
   bug_tracker_uri: https://github.com/SerylLns/data_porter/issues
   rubygems_mcp_server_uri: https://rubygems.org/gems/data_porter
   rubygems_mfa_required: 'true'

data/bookmarklet.md

@@ -1,217 +0,0 @@
----
-title: "Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data"
-published: false
-tags: javascript, webdev, architecture, bookmarklet
----
-
-# Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data
-
-We’re in 2008.
-
-The iPhone 3G just dropped. Facebook crosses 100 million users. Bitcoin quietly appears on a cryptography mailing list. The web is shifting.
-
-And while the world is obsessing over apps and platforms… we’re going back to something beautifully simple.
-
-**A bookmarklet.**
-
-No extension store review.  
-No packaging.  
-No deployment delays.
-
-Just a small piece of JavaScript living inside a browser bookmark — capable of injecting a clean, isolated UI into any e-commerce page, detecting product data automatically, and sending it to your backend.
-
-One click. Any product page. Instant extraction.
-
-Here’s how the architecture works.
-
----
-
-## High-Level Architecture
-
-The clipper follows a simple execution model:
-
-1. The bookmarklet injects a remote script into the current page.
-2. The script scans the DOM using multiple detection strategies.
-3. A sidebar panel renders inside a Shadow DOM (fully isolated).
-4. Detected products are visually highlighted.
-5. The user selects items to import.
-6. Selected data is sent to the backend for processing.
-
-No browser extension. No build complexity. Just runtime execution.
-
----
-
-## Why a Bookmarklet?
-
-For a user-triggered action ("Import this page"), a bookmarklet offers strong trade-offs:
-
-|             | Bookmarklet           | Browser Extension                |
-| ----------- | --------------------- | -------------------------------- |
-| Install     | Drag a link           | Store review required            |
-| Updates     | Instant (server-side) | Requires store re-approval       |
-| Permissions | None                  | Explicit permission prompts      |
-| Maintenance | Single hosted file    | Multi-file manifest architecture |
-
-If your tool runs only when explicitly triggered, a bookmarklet is often the leanest solution.
-
----
-
-## Product Detection Strategy
-
-No single detection method works across all e-commerce sites.
-
-A robust clipper layers multiple strategies, ordered by confidence:
-
-- **Structured Data (JSON-LD)**  
-  Many sites expose `schema.org/Product` data for SEO.
-- **Microdata attributes**
-- **OpenGraph metadata**
-- **Heuristic DOM scanning**
-- **URL pattern matching (fallback)**
-
-The key principle is:
-
-> Prefer high-confidence structured data, then gracefully degrade.
-
-### Example: Extracting JSON-LD Products
-
-```javascript
-function extractFromJsonLd() {
-  const scripts = document.querySelectorAll(
-    'script[type="application/ld+json"]',
-  );
-  const products = [];
-
-  scripts.forEach((script) => {
-    try {
-      const data = JSON.parse(script.textContent);
-      // Traverse recursively and collect Product objects
-      collectProducts(data, products);
-    } catch (e) {}
-  });
-
-  return products;
-}
-```
-
-In practice, you normalize URLs, merge duplicates, and score sources by confidence before presenting results.
-
-The goal is reliability, not perfection.
-
----
-
-## Shadow DOM: Isolation Is Non-Negotiable
-
-Injecting UI into arbitrary websites is dangerous.
-
-CSS resets, `!important` rules, framework styles — they will break your interface.
-
-Shadow DOM solves this by creating an isolated rendering tree:
-
-```javascript
-const host = document.createElement("div");
-document.body.appendChild(host);
-
-const shadow = host.attachShadow({ mode: "open" });
-shadow.innerHTML = `
-  <style>
-    :host { all: initial; font-family: system-ui; }
-    .panel { position: fixed; right: 0; top: 0; }
-  </style>
-  <div class="panel">Clipper UI</div>
-`;
-```
-
-Key principle:
-
-> Your UI must behave identically on Shopify, Magento, custom React apps, or legacy PHP pages.
-
-Isolation is mandatory.
-
----
-
-## Visual Feedback & Interaction Control
-
-When products are detected, highlighting them directly on the page improves user confidence.
-
-Because many e-commerce sites attach their own click handlers (analytics, routing, SPA navigation), event handling must be carefully managed.
-
-Best practice:
-
-- Use capture phase listeners
-- Prevent unintended navigation
-- Clean up all listeners and styles on teardown
-
-A clipper should leave **zero traces** after closing.
-
----
-
-## Backend Communication
-
-Once items are selected, the clipper sends a structured payload to your backend.
-
-The backend typically:
-
-- Normalizes URLs
-- Deduplicates products
-- Associates them with a source domain
-- Triggers downstream processing (price tracking, enrichment, etc.)
-
-Security considerations:
-
-- Use scoped, short-lived API tokens
-- Never expose sensitive credentials
-- Sanitize all extracted DOM content before rendering
-
----
-
-## Limitations
-
-A bookmarklet runs inside the page’s context. That comes with constraints.
-
-### Content Security Policy (CSP)
-
-Strict `script-src` headers can block injected scripts entirely.
-There is no client-side workaround. A browser extension is required in those cases.
-
-### Single Page Applications (SPAs)
-
-React/Next.js apps often load content asynchronously.
-Mutation observers or delayed scans improve detection reliability.
-
-### Bot Protection (Backend)
-
-While the bookmarklet runs in the user’s real browser session, backend scraping of submitted URLs may face anti-bot systems.
-That is a server-side concern.
-
----
-
-## Legal & Ethical Considerations
-
-If you build a commercial tool around product extraction:
-
-- Only collect publicly visible data
-- Do not bypass authentication or CAPTCHAs
-- Respect rate limits
-- Be transparent about data usage
-- Review relevant laws (CFAA, GDPR, local regulations)
-
-User-initiated clipping is typically lower risk than automated crawling, but not risk-free.
-
----
-
-## Lessons Learned
-
-1. **Isolation first.** Shadow DOM prevents 90% of UI conflicts.
-2. **Layered detection beats single heuristics.**
-3. **Keep it framework-free.** Dependencies increase fragility.
-4. **Design for hostile environments.** You do not control the host page.
-5. **Simplicity wins.** A single hosted file can outperform complex extension architectures.
-
----
-
-A bookmarklet is not flashy.
-
-But when designed correctly, it becomes a powerful bridge between arbitrary web pages and your product.
-
-Sometimes the most effective architecture is the one that avoids complexity entirely.