Libre Translate

Welcome to Libre Translate

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

With the release of version 2.1.3, Libre Translate has evolved into a complete Enterprise-Grade localization solution. It was built from the ground up to handle high-traffic environments, massive WooCommerce catalogs, and dynamic content injection.

Featuring Dual-Layer Server Caching, a resilient Resumable Bulk Preloader, and true Live DOM Swapping, your website will deliver translated pages faster than ever, natively preserving your original HTML structure and SEO markup.

Phase 1: Running Your Private Translation Server

For the plugin to operate without restrictions, you must deploy the open-source LibreTranslate engine on your VPS or Dedicated Server. We highly recommend a server running Ubuntu 20.04 or 22.04 LTS with at least 2GB of RAM and 2 CPU cores.

To ensure maximum security and prevent unauthorized access, we will bind the server exclusively to your local loopback interface. This means the engine will only respond to requests originating from your own machine.

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 Secure Engine: Execute the command below. Adjust the LT_LOAD_ONLY variable to include only the language codes you intend to use (e.g., en, de, fr, es). Reducing the number of loaded languages drastically lowers RAM consumption. Set LT_THREADS based on your available CPU cores.

   docker run -d --name libretranslate --restart unless-stopped -p 127.0.0.1:5000:5000 -e LT_THREADS=4 -e LT_LOAD_ONLY=en,de,it,fr,es libretranslate/libretranslate

4. Configure the Reverse Proxy: In your hosting management panel (cPanel, Plesk, CloudPanel, or RunCloud), create a new subdomain (e.g., api.yoursite.com). Set up an Nginx or Apache Reverse Proxy to route incoming secure HTTPS traffic on port 443 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 for your API subdomain. The WordPress plugin requires a secure https:// connection to communicate properly.

Phase 2: Plugin Installation & Configuration

With your private API engine successfully deployed, the next step is connecting it to your WordPress installation. This process takes less than two minutes.

1. Log in to your WordPress administrative dashboard. Navigate to Plugins -> Add New -> Upload Plugin. Upload the provided libre-translate.zip archive and activate the plugin.
2. Locate the new menu item in your sidebar and go to Settings -> Libre Translate.
3. In the Your API Server URL field, enter the full, secure URL of the proxy you set up in Phase 1 (e.g., https://api.yoursite.com). Do not include a trailing slash.
4. If you set up an API Key during your Docker installation (optional advanced step), enter it in the API Key field. Otherwise, leave it blank.
5. Click the Test Connection button. The plugin will attempt to send a tiny payload to your server. A green success message confirms that WordPress can communicate with your engine.
6. Select your Primary Site Language (the language your site is currently written in).
7. Check the boxes for the target translation languages you wish to offer to your visitors. Only select languages you actually loaded into your Docker container.
8. Configure the visual appearance of your floating language switcher (position, colors, and flag style) and click Save Changes.

Phase 3: Server Caching & Resumable Preloader

Translating an entire web page dynamically takes server power. To guarantee instant 0.1ms load times for returning visitors and protect your API from being overwhelmed during traffic spikes, version 2.1 introduces an Enterprise-grade caching ecosystem.

1. Dual-Layer Intelligent Caching

By enabling the "Enable Database/Redis Caching" option, your server will memorize every single translated string. The system uses a Dual-Layer approach:

• Memory Layer (Primary): If your server runs an object cache like Redis or Memcached, translations are stored directly in your server's RAM. This allows for microscopic retrieval times.
• Database Layer (Fallback): If no object cache is detected, translations are safely indexed in a custom, optimized table within your WordPress MySQL database.

2. The Resumable Bulk Cache Preloader

If you manage a large portal or WooCommerce store with thousands of URLs, waiting for user traffic to build your cache is inefficient. You can proactively translate the entire website in the background.

• Scroll to the "Bulk Actions" section at the bottom of the plugin settings.
• Select the specific languages you wish to generate cache for.
• Click Start Preloading. The integrated Sitemap Crawler will map your entire site architecture and begin fetching URLs in smart, throttled batches (500 pages at a time) to ensure your CPU usage remains stable.

Phase 4: Advanced Setup (SEO Subdomains)

By default, Libre Translate operates using URL query parameters (e.g., yoursite.com/?lang=de). While functional, search engines like Google prefer distinct URLs for multi-regional indexing. For a professional, SEO-optimized structure, you can activate the Subdomain routing feature (e.g., de.yoursite.com).

1. Configure Wildcard DNS Records: Log in to your domain registrar or DNS management panel (such as Cloudflare, Namecheap, or Route53). Add a Wildcard A Record. (Type: A, Name: *, Value: Your Main Server IP). Wait 15-30 minutes for DNS propagation.
2. Hosting Panel Setup (Domain Aliasing): Your web server needs to know how to handle requests coming to these new subdomains.
   • Plesk Users: Navigate to Websites & Domains and click "Add Domain Alias". Enter the subdomain name (e.g., de.yoursite.com). CRITICAL: You must uncheck the option "Redirect with the HTTP 301 code", otherwise the translation will fail. Generate a Let's Encrypt SSL for the alias.
   • cPanel Users: Navigate to "Parked Domains" or "Aliases". Add your new subdomain and ensure its document root points exactly to your main /public_html directory. Run AutoSSL to secure it.
3. Plugin Activation: Return to the Libre Translate settings in WordPress. Change the "Translation Link Format" dropdown from URL Parameters to Subdomains. Save changes.

Note on Link Rewriting: You do not need to manually change links in your content. Our proprietary Subdomain Link Rewriter engine automatically intercepts all internal HTML anchor tags and rewrites them on the fly. This ensures that once a visitor enters the de. subdomain, all internal navigation clicks keep them locked into that localized environment.

Phase 5: Premium Configuration & Protection

1. Brand Protection (Dictionary Exclusion)

Machine translation is literal, which can be problematic for branded terminology. If your company name is "Apple", you do not want it translated to "Manzana" in Spanish. To prevent this, locate the Excluded Words text area in the settings. Enter your brand names, product titles, or industry-specific acronyms (one word per line). The engine will wrap these terms in protective, non-translate HTML tags before sending the payload to the server.

2. Granular Per-Page Exclusion

Certain legal documents, such as a localized Privacy Policy or a highly specific Terms of Service page, may require strictly manual translation to maintain legal binding. Open any page, post, or custom post type in the standard WordPress Editor. Look at the right-side document panel for the "Libre Translate" meta box. Check the box labeled "Exclude this entire page from automated translation" and update the post. The translation module will completely ignore this URL.

3. Shortcode & Native Placement

While the floating, fixed-position language switcher is popular, you may prefer a more integrated design. In the settings, change the "Menu Position" to Shortcode Only. You can then paste the shortcode

inside any Elementor widget, Gutenberg block, sidebar, or PHP header file (using do_shortcode). This allows you to position the language dropdown natively within your site's header navigation or footer matrix.

Phase 6: WooCommerce & Dynamic DOM Integrity

Standard translation plugins often fail spectacularly on modern eCommerce sites because WooCommerce injects text asynchronously (AJAX) after the page has fully loaded. Libre Translate is engineered to handle dynamic environments flawlessly.

• MutationObserver Technology: When a user clicks "Add to Cart", the button text often changes to "Adding..." dynamically. Our custom Vanilla JS translation scanner attaches a MutationObserver to the document body. It watches the DOM tree in real-time. The microsecond new English text is injected into the screen, it intercepts it, fetches the translation from cache, and swaps it without breaking the user's flow.
• Checkout Security Protocols: Caching private user data is a severe security risk. The Libre Translate engine automatically detects standard WooCommerce endpoints (/cart, /checkout, /my-account) and entirely disables database caching for these routes. It strictly relies on Live DOM Swapping, ensuring session nonces and personal details are never stored or exposed.
• Zero-Flicker Live DOM Swapping: When users navigate via URL parameters, the plugin does not force a hard reload of the page assets. It securely queries the API and seamlessly manipulates the text nodes directly in the browser's memory. This is paired with an Anti-Flicker CSS overlay to prevent "Flash of Original Text" (FOOT) during the millisecond transition phase.