Welcome to NorthPublisher Libre Translate

This revolutionary WordPress plugin allows you to offer instant, unlimited translations of your website using the open-source LibreTranslate engine. Say goodbye to monthly API subscriptions, strict rate limits, and per-word billing structures that punish your business for growing.

The plugin is available in two tiers: a robust FREE version for basic sites, and a powerful PRO version designed to handle high-traffic environments, massive WooCommerce catalogs, and dynamic content injection.

PRO unlocks crucial features for serious websites: SEO Subdomains for global indexing, a Resumable Bulk Preloader for instant load times, and ultra-fast JSON File Caching. Both versions feature true Live DOM Swapping to preserve your original HTML structure.

Phase 1: Running Your Private Translation Server

To use this plugin without restrictions, you connect it to a LibreTranslate API endpoint. You can host this yourself for free on a VPS.

Alternatively, if you choose to self-host, we recommend a server running Ubuntu 20.04 or 22.04 LTS. We will bind the server to your local loopback interface for security.

1. Access your server via SSH terminal using a client like PuTTY or Terminal (macOS), logging in as the root user.
2. Install Docker Environment: If you don't have Docker installed, run the official installation script:

   curl -fsSL https://get.docker.com | sh
   systemctl enable docker
   systemctl start docker

3. Deploy the Engine: Execute the command below.
   
   Crucial Performance Tip: Set LT_THREADS based on your available CPU threads (e.g., if your server has 16 threads, use 12, leaving some for OS overhead). Adjust the --load-only argument to include only the languages you need to save RAM. Add -e PYTHONWARNINGS="ignore" to keep logs clean.

   docker run -d -p 127.0.0.1:5000:5000 \
     --name libretranslate_engine \
     --restart unless-stopped \
     -e LT_THREADS=4 \
     -e PYTHONWARNINGS="ignore" \
     libretranslate/libretranslate \
     --disable-web-ui \
     --load-only en,de,it,fr,es

4. Configure the Reverse Proxy: In your hosting panel, create a subdomain (e.g., api.yoursite.com). Set up an Nginx/Apache Reverse Proxy to route incoming HTTPS traffic to your internal Docker container running on http://127.0.0.1:5000.
5. Secure with SSL: Ensure you generate a valid Let's Encrypt SSL certificate. The WordPress plugin requires a secure https:// connection.

Phase 2: Plugin Installation & Configuration

With your API engine deployed (or a third-party API ready), connect it to your WordPress installation.

1. Go to Plugins -> Add New -> Upload Plugin. Upload the provided `.zip` archive and activate the plugin.
2. Navigate to Settings -> Libre Translate.
3. In the API Server URL field, enter the full URL of your API (e.g., https://api.yoursite.com). Do not include a trailing slash.
4. If your server requires an API Key, enter it here. (If a key is saved, requests securely route through WordPress's admin-ajax.php proxy, so the key is never exposed).
5. Translation Transport: FREE users default to the WP proxy for reliability. Developers can enable direct browser translation via the nlt_free_use_browser_translate filter.
6. Click Test Connection. A green message confirms WordPress can reach the engine.
7. Select your Primary Language and check the target languages.
8. Configure the floating language switcher and Excluded Words (protect brand names from translation), then click Save Changes.

Phase 3: Caching & Bulk Preloader PRO

Real-time DOM translation is fast, but fetching from the API repeatedly is inefficient. PRO unlocks enterprise caching and preloading for ultimate performance.

1. Server Translation Cache

Enable the cache to store translated strings. In the PRO version, you should select JSON files (recommended). This stores the cache directly on your disk (in wp-content/uploads), bypassing the database entirely for blazing-fast retrieval.

2. The Resumable Bulk Cache Preloader

Don't wait for visitors to generate the cache. The PRO preloader automatically crawls your sitemap and translates pages in the background. This is the key to unlocking peak performance.

• Scroll to the "Bulk Cache Preloader" section.
• Select the languages to preload.
• Click Start Preloading.

Phase 4: SEO Subdomains & Slugs PRO

The FREE version uses URL parameters (?lang=de). To rank globally on search engines, Subdomain Routing is crucial. PRO provides a native, SEO-optimized structure (e.g., de.yoursite.com).

1. Configure Wildcard DNS: Add a Wildcard A Record (Name: *, Value: Your Server IP) in your DNS manager (e.g., Cloudflare).
2. Hosting Setup: Ensure your hosting panel routes these subdomains to your main WordPress installation (e.g., Domain Alias without 301 redirection).
3. Enable Subdomain Mode: In plugin settings, change "Translation Link Format" to Subdomain. The plugin's built-in URL Rewriter handles internal links automatically.
4. Enable SEO Translated URLs & Titles: Turn this ON to generate native slugs for Posts, Pages, and Products.
   The plugin automatically handles:
   • Canonical Alignment: 301 redirects for incorrect language/slug mismatches.
   • Hreflang Tags: Injects hreflang and x-default links in the header. (Note: Avoid duplicating hreflang generation with other SEO plugins to prevent conflicts).
   • Translates <title> and og:title automatically.

Subdomain First-Load Speed Mode: Ensure this is enabled in PRO. It skips initial dictionary warm-up routines on the first hit, resulting in significantly faster "first paint" times for visitors entering via subdomains.

Phase 5: Performance Tuning

Fine-tune the engine's behavior based on your hosting environment.

• Shared Hosting Mode Uses smaller API batches (25 strings instead of 100). Essential for cPanel/shared hosting to prevent 504 timeouts and memory exhaustion.
• Translation Throughput Controls batch sizes and parallelism. Choose Conservative (weak hosting), Balanced (default), or Aggressive (strong VPS).
• Translation Intensity Multiplies the batch sizes. Options: Normal, Turbo, Max. Warning: Combining Turbo/Max with Shared Hosting Mode can cause severe CPU spikes and API throttling.
• Preloader Throttle PRO Adjust the speed (Fast, Normal, Slow) of the Bulk Preloader to prevent overwhelming your server during massive background jobs.

Phase 6: WooCommerce Ready

WooCommerce injects content dynamically via AJAX (cart updates, infinite scroll). Standard plugins often enter infinite translation loops here. NorthPublisher Libre Translate uses an intelligent MutationObserver to handle this gracefully.

Advanced Observer Tuning PRO

PRO unlocks crucial controls to prevent API churn on heavy eCommerce sites:

• Observer Cooldown (ms): Enforces a mandatory pause (e.g., 3000ms) after a translation pass completes before allowing a new one, preventing rapid-fire loops on product pages.
• Observer Min Segments: Forces the plugin to wait until a minimum number of new text strings (e.g., 12) are detected before calling the API, reducing tiny, wasteful API bursts.
• Skip Noisy Dynamic Blocks: Automatically ignores high-churn, low-value dynamic mounts (like login modals or Google Pay widgets) where translation ROI is low but server impact is high.

Note: The plugin automatically pauses the MutationObserver while a translation run is in progress to avoid feedback loops.

Phase 7: Debugging & Tools

If translations aren't working as expected, use the built-in tools.

• Frontend Debug Mode: Append ?nlt_debug=1 to any URL to open the floating Debug Panel and view Console logs.
• Admin Tools Tab: Use the "Open Debug on any URL" feature to quickly test specific pages.
• Test Connection: Use the button in Settings to verify API reachability.