Migration Guide

This guide helps you migrate from the separate Simplify and Translator plugins to the unified plugin.

What Changed

Before (v1): Separate Plugins

<!-- Translator Plugin -->
<script>
  window.PTP_TRANSLATE_CONFIG = {
    sourceLang: "de",
    targetLangs: [{ code: "en" }, { code: "fr" }],
  };
</script>
<script src="https://api.participaite.de/static/{{client_id}}/ptpSimplify.js"></script>

<!-- Simplify Plugin -->
<script>
  window.PTP_TRANSLATE_CONFIG = {
    targetElementSelector: "main",
  };
</script>
<script src="https://api.participaite.de/static/{{client_id}}/ptpTranslate.js"></script>

After (v2): Unified Plugin

<!-- Single Unified Plugin -->
<script>
  window.PTP_TRANSLATE_CONFIG = {
    translator: {
      enabled: true,
      sourceLang: "de",
      targetLangs: [{ code: "en" }, { code: "fr" }],
    },
    LS: {
      enabled: true,
      targetElementSelector: "main",
    },
  };
</script>
<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

Migration Steps

Step 1: Update Configuration Object

From Translator Plugin

Before:

window.PTP_TRANSLATE_CONFIG = {
  sourceLang: "de",
  targetLangs: [{ code: "en" }, { code: "fr" }],
  placement: {
    type: "floating",
    position: "bottom-right",
  },
};

After:

window.PTP_TRANSLATE_CONFIG = {
  translator: {
    enabled: true,
    sourceLang: "de",
    targetLangs: [{ code: "en" }, { code: "fr" }],
    buttonPlacement: {
      type: "floating",
      position: "bottom-right",
    },
  },
};

From Simplify Plugin

Before:

window.PTP_TRANSLATE_CONFIG = {
  targetElementSelector: "main",
  buttonPlacement: "floating",
  buttonFloatingPosition: "bottom-left",
  accentColor: "#007bff",
};

After:

window.PTP_TRANSLATE_CONFIG = {
  LS: {
    enabled: true,
    targetElementSelector: "main",
    buttonPlacement: {
      type: "floating",
      position: "bottom-left",
    },
    accentColor: "#007bff",
  },
};

Step 2: Update Script Tags

Remove the old script tags and replace with the unified one:

Remove:

<script src="https://api.participaite.de/static/{{client_id}}/ptpSimplify.js"></script>
<script src="https://api.participaite.de/static/{{client_id}}/ptpTranslate.js"></script>

Add:

<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

Step 3: Add New Features (Optional)

Take advantage of the new EAS functionality:

window.PTP_TRANSLATE_CONFIG = {
  translator: {
    // ... existing translator config
  },
  EAS: {
    enabled: true,
    buttonPlacement: {
      type: "floating",
      position: "middle-left",
    },
  },
  LS: {
    // ... existing LS config
  },
};

Configuration Mapping

Translator Plugin Mapping

v1 Property	v2 Property
window.PTP_TRANSLATE_CONFIG	window.PTP_TRANSLATE_CONFIG.translator
sourceLang	translator.sourceLang
targetLangs	translator.targetLangs
placement	translator.buttonPlacement
dropdownStyle	translator.dropdownStyle

Simplify Plugin Mapping

v1 Property	v2 Property
targetElementSelector	LS.targetElementSelector
buttonPlacement	LS.buttonPlacement.type
buttonFloatingPosition	LS.buttonPlacement.position
offsetX	LS.buttonPlacement.offset.x
offsetY	LS.buttonPlacement.offset.y
accentColor	LS.accentColor
noTranslateHandles	LS.noTranslateHandles
noTranslateUrls	LS.noTranslateUrls
skipSelectors	LS.skipSelectors
skipTextSelectors	LS.skipTextSelectors
metaInfos	LS.metaInfos

Complete Migration Examples

Example 1: Full Feature Migration

Before (v1):

<!-- Translator -->
<script>
  window.PTP_TRANSLATE_CONFIG = {
    sourceLang: "de",
    targetLangs: [
      { code: "en", label: "English" },
      { code: "fr", label: "Français" },
    ],
    placement: {
      type: "inside",
      buttonContainer: "#nav-languages",
    },
    dropdownStyle: {
      accentColor: "#2563eb",
    },
  };
</script>

<!-- Simplify -->
<script>
  window.PTP_TRANSLATE_CONFIG = {
    targetElementSelector: "main",
    buttonPlacement: "floating",
    buttonFloatingPosition: "bottom-right",
    accentColor: "#059669",
    skipSelectors: [".sidebar", ".ads"],
  };
</script>

<script src="https://translator.participaite.de/ptp-translate-plugin"></script>
<script src="https://translator.participaite.de/ptp-simplify.js"></script>

After (v2):

<script>
  window.PTP_TRANSLATE_CONFIG = {
    translator: {
      enabled: true,
      sourceLang: "de",
      targetLangs: [
        { code: "en", label: "English" },
        { code: "fr", label: "Français" },
      ],
      buttonPlacement: {
        type: "inside",
        buttonContainer: "#nav-languages",
      },
      dropdownStyle: {
        accentColor: "#2563eb",
      },
    },

    LS: {
      enabled: true,
      targetElementSelector: "main",
      buttonPlacement: {
        type: "floating",
        position: "bottom-right",
      },
      accentColor: "#059669",
      skipSelectors: [".sidebar", ".ads"],
    },

    // New feature!
    EAS: {
      enabled: true,
      buttonPlacement: {
        type: "floating",
        position: "bottom-left",
      },
    },
  };
</script>

<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

Example 2: Translation Only

Before (v1):

<script>
  window.PTP_TRANSLATE_CONFIG = {
    sourceLang: "de",
    targetLangs: [{ code: "en" }],
  };
</script>
<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

After (v2):

<script>
  window.PTP_TRANSLATE_CONFIG = {
    translator: {
      enabled: true,
      sourceLang: "de",
      targetLangs: [{ code: "en" }],
    },
  };
</script>
<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

Breaking Changes

Minimal Breaking Changes

• Script URLs: Use the unified script URL for all functionality

No Breaking Changes

• Button Behavior: All buttons work exactly as before
• API Compatibility: The public API remains unchanged
• Styling: Custom CSS continues to work

Validation and Testing

After migration:

1. Test all features that were previously working
2. Check browser console for any deprecation warnings
3. Verify button placement matches your expectations
4. Test translation functionality in all configured languages
5. Verify simplification works with your content

Migration Checklist

• Update configuration object structure
• Replace multiple script tags with single unified script
• Test translation functionality
• Test LS/simplification functionality
• Consider enabling new EAS feature
• Update any custom CSS if needed
• Remove deprecated configuration warnings
• Test on all target browsers
• Update documentation/comments in code

---

Need Help?

If you encounter issues during migration:

• Configuration Reference - Complete configuration guide
• Troubleshooting - Common migration issues