Skip to content
LionrapidLionRapid Docs

WordPress plugin

The LionRapid WordPress plugin translates a WordPress site server-side: it buffers the HTML WordPress renders, replaces the text with translations from your LionRapid project, fixes the SEO metadata, and sends the translated page to the browser. Search engines see fully translated HTML, no JavaScript is required for the translation itself, and new text on your site is discovered and synced to the platform for translation automatically.

It shares its backend, cache format, and key conventions with the JavaScript SDK, so a WordPress site and an app can live in the same continuous project.

Install and connect

Section titled “Install and connect”
  1. Install the plugin (during early access the plugin is provided as a ZIP — upload it via Plugins → Add New → Upload Plugin and activate it).
  2. Open Settings → LionRapid and connect it to your project:
    • Server URL — your LionRapid host.
    • API key — an integration key for the continuous project (see Authentication).
    • Default language — the language your site is written in.
    • Default namespace — where the site’s strings live in the project (app by default).
    • Enabled languages — the languages visitors can switch to.
  3. Use the built-in connection test on the settings page to confirm the plugin can reach the server, then visit a page under a language prefix (for example /es/about/).

How a page gets translated

Section titled “How a page gets translated”

For every front-end request the plugin:

  1. Detects the language from the URL path. /about/ serves the default language untouched; /es/about/ serves Spanish. Only languages you enabled are recognized.
  2. Buffers the rendered page. WordPress renders normally — theme, plugins, blocks — and the plugin captures the final HTML via output buffering, so it works with any theme without template changes. Admin pages, AJAX, REST, and cron requests are skipped.
  3. Finds translatable text in the DOM (see the two modes below).
  4. Fetches translations, from its local cache first, then from the platform.
  5. Replaces the text and marks translated elements with data-lionrapid-translated="1".
  6. Applies SEO handling (see below) and returns the page.

New, never-seen text is shown in the original language on the first request, queued, and synced to the platform in the background — it shows up translated once translators (or MT) have handled it.

Translation modes

Section titled “Translation modes”

Auto mode (default) translates all visible text, with guardrails:

  • Text inside <script>, <style>, <code>, <pre>, <textarea>, <noscript>, and <svg> is never touched.
  • Elements with translate="no" or data-no-translate, and anything matching your configured exclude selectors, are skipped.
  • Auto-exclude patterns skip text that shouldn’t be translated even though it is visible: email addresses, URLs, pure numbers, and phone numbers (each toggleable in settings), plus anything shorter than the configured minimum text length.
  • Excluded paths let you switch off translation for whole URL sections.

Auto-detected text is keyed by a hash of its content, so the same sentence appearing on ten pages is one string in your project.

Explicit mode translates only elements that carry a data-i18n attribute:

<span data-i18n="welcome">Welcome to our shop</span>
<span data-i18n="checkout:total">Total</span>

A key without a namespace prefix gets the default namespace (welcome → app:welcome). Explicit mode trades coverage for precision: nothing is translated by accident, and every string has a stable, semantic key that translators see in context. In auto mode, data-i18n still works — elements that have it use their named key instead of a hash.

SEO behavior

Section titled “SEO behavior”

Translated pages come out SEO-correct without extra plugins:

  • lang attribute — <html lang="es"> is set to the served language.
  • hreflang alternates — a <link rel="alternate" hreflang="…"> tag is injected for every enabled language, plus an x-default pointing at the default-language URL, so search engines index each language variant correctly.
  • Path-based URLs — each language lives under its own path prefix (/es/…, /de/…), which keeps language variants crawlable and shareable as distinct URLs.
  • Meta tags — the meta description and Open Graph tags are translated along with the page body.

Gutenberg blocks

Section titled “Gutenberg blocks”

The plugin registers blocks for the block editor:

  • Translation block — renders a translation by key, with optional parameters, and outputs the data-i18n markup for you. Authors pick the key; the plugin resolves the translation server-side on every request.
  • Language switcher block — a list of links to the current page in every enabled language, using the path-prefixed URLs.

Blocks are the recommended way to put named keys into content: unlike auto-detected text, a block’s key survives copy edits (editing the text in one language doesn’t orphan the translations).

Caching and sync

Section titled “Caching and sync”

The plugin caches translations in WordPress options using the same key format as the SDK: locale:namespace:key for individual strings and @locale:namespace for whole-namespace payloads, with values stored as { text, styles } content units. Lookups go individual key → namespace bulk → server.

Sync runs in the background, after the response is sent:

  • Newly discovered text is batched and pushed to the platform’s batch sync endpoint with your integration key as bearer auth (endpoint detail in the Platform API reference).
  • Once a string is synced its status is pending — the original text is served until a translation exists, then the refreshed cache takes over.
  • The cache is refreshed from the server after each sync round, and cache TTL/enablement are configurable in settings.

Settings reference

Section titled “Settings reference”
Setting What it controls
Enabled Master switch for the plugin
Server URL / API key Connection to your LionRapid project
Default language Source language of the site
Default namespace Namespace for the site’s strings
Enabled languages Languages served under path prefixes
Translation mode auto (all visible text) or explicit (data-i18n only)
Minimum text length Shortest text auto mode will pick up
Exclude paths URL sections that are never translated
Exclude selectors CSS selectors auto mode skips
Auto-exclude toggles Skip emails, URLs, numbers, phone numbers
Cache enabled / TTL Local translation cache behavior
Output buffering Master switch for server-side page translation

Troubleshooting

Section titled “Troubleshooting”
  • Nothing is translated — check that you are on a non-default language URL (/es/…), the language is in the enabled list, and the connection test passes.
  • A string stays in the source language — first visits show the original by design; check the continuous project for the synced string and its translation status.
  • Something is translated that shouldn’t be — add an exclude selector, or put data-no-translate on the element; for structured content prefer explicit mode.
  • Verifying output — translated elements carry data-lionrapid-translated="1", and the <html lang> attribute reflects the served language, so both are easy to check in the page source.