You already have WPML running. Your languages, URLs and translated pages belong there. What you want to change is the translation engine: use an API account you control, choose the model yourself, and see the bill in that provider’s dashboard.
This guide connects Lumo AI Translation Addon for WPML, sends one carefully chosen page, and explains what to check before expanding the queue. The useful milestone is not a green connection test. It is a translated page that preserves the original facts, links and layout.
Disclosure and scope: LumoWP makes this add-on. This tutorial is based on a review of version 3.20.28, its settings and integration code, official documentation, and nine isolated PHP contract checks. Those checks did not call a paid API or complete a live WPML translation job. The graphics are instructional illustrations; the connection panel is adapted from our product documentation. Menu labels can differ between WPML versions.
Start with one page and one language
Use a staging copy and back up existing translations before changing editors or running bulk tools. A successful API request does not prove that a complete page was saved correctly or that its translation is ready for readers.
1. Understand where your API key belongs
There are three separate responsibilities. WPML manages languages and translation relationships. Lumo receives assigned jobs and sends translatable content to the chosen AI provider. The provider generates text and bills your API account according to its terms.
Your provider key belongs in Lumo WP → AI Translator → Settings. It is not a WPML registration key, a Lumo license key, or a replacement value to paste into WPML’s Advanced Translation Editor. WPML’s own automatic translation has its own billing workflow. This guide describes a third-party job-processing route.
The Lumo WPML AI Translation Addon provides that route. Direct-provider choices in the reviewed build include OpenAI, Anthropic, Google Gemini, xAI Grok, DeepSeek and Mistral. The license and API usage are separate costs. Using your own key does not mean free inference or unlimited provider capacity.
An API key is not an arbitrary API URL. The normal settings screen selects supported providers. A private proxy or self-hosted endpoint needs a compatible request and response contract; changing the destination alone is not enough.
2. Prepare WPML before installing the add-on
First make sure the original page is correct. A translation system cannot reliably repair an incorrect return policy, an ambiguous specification or a broken source link.
- Confirm the source language and add only the target language you need for the pilot.
- Open an existing translated page and record its URL and editor workflow.
- Back up the database and translations a reviewer has already edited.
- Check that your WPML setup supports translation management and its required components are active. Install String Translation when your scope includes registered strings.
- Keep the pilot away from private customer and account content.
Pay attention to the translation editor
In version 3.20.28, activation schedules a switch to WPML’s Classic Translation Editor when the integration is ready. The source writes WPML’s translation-editor setting; this is not merely a different-looking button inside Lumo.
That matters if existing pages use the Advanced Translation Editor. Test an existing job and its edits on staging before changing an established multilingual store. Record the previous editor selection, resolve outstanding jobs deliberately, and avoid having two workflows rewrite the same page.
WPML documents the selector under WPML → Settings → Translation Editor in its Classic Translation Editor guide. Follow the documentation for your installed version if that section has moved.
3. Install Lumo and connect your provider
Download the plugin ZIP from your LumoWP account. Open Plugins → Add New Plugin → Upload Plugin, choose the ZIP, install it and activate it. Complete normal product-license activation. Your AI API key is a separate credential and will not activate the plugin license.
Open Lumo WP → AI Translator → Settings. Under AI Provider Configuration, select the provider that issued your key. Choose a model available to that API account. Appearing in a plugin catalog does not establish that a model remains available upstream or that your account can call it.
Use a dedicated API project or credential for translation where your provider supports that separation. Set appropriate usage alerts and limits. Check whether the provider enforces a hard cap: a budget notification alone may not stop spending.
For Gemini, Google explains key management in Google AI Studio. For other providers, use their official API dashboards. Keep keys out of page content, screenshots, browser-side scripts and support messages.
Paste the key into API Key, choose AI Model, and click Save All Settings. Only then use Test connection.
What the test actually proves
The reviewed implementation sends a short English-to-Persian string with a random marker, using the saved provider, key and model. A successful result shows that this small request worked through the current adapter. It does not test your intended language pair, long-content chunking, every page field or WPML’s final save step.
Changing a model and testing before saving can test the previous configuration by mistake. This is why the order matters.
The reviewed settings store the key in a database setting. A masked input field is not evidence of encryption at rest. Restrict administrator access and protect backups. Selected content also leaves WordPress for the configured provider; check its data-handling terms before sending private material.
4. Write instructions you can verify
Open Settings → Custom Instructions. Start with global rules, then add short instructions for titles, body text, Elementor labels or taxonomy terms where their requirements differ.
“Make it professional” leaves too much room for interpretation. “Keep the product code NB-240 unchanged” gives you something you can check. For a fictional product-page pilot, try:
Translate the meaning faithfully into the target language.
Keep Northbridge and the product code NB-240 unchanged.
Preserve quantities, measurements and warranty durations.
Do not add discounts, certifications, benefits or promises.
Keep URLs, HTML attributes and placeholders unchanged.
Return only the translation, without notes or explanations.
For titles, preserve the product name and forbid invented superlatives. For Elementor buttons, ask for a concise equivalent of the original action. A “Download guide” button should not quietly become “Buy now.”
These are instructions, not compiler-enforced validation rules. Even a clear prompt can be misunderstood. A reviewer still needs to compare the output with its source.
5. Configure a conservative pilot
Chunk length, batch size, timeout and delay solve different problems. Increasing all of them does not make a queue more reliable.
| Setting | Pilot approach | What it changes |
|---|---|---|
| Queue Batch Size | Start at 1 | Jobs selected per batch; not a token budget |
| Max Content Length (chars) | Keep the current value initially | A chunking parameter in characters, not provider tokens |
| Enable Content Chunking | Keep enabled for long content | Handles large content in smaller pieces |
| Chunk Delay | Begin with the existing value | Spacing in relevant chunk-processing paths |
| Enable Background Processing | Enable when ready for the pilot | Automatic queue processing through scheduling |
| Keep original URL slug | Decide before creating many translations | Slug handling, not an indexing guarantee |
One version-specific detail deserves attention. The UI describes Processing Timeout as an API-request limit, but the reviewed request method uses max(300, $this->processing_timeout). In that path, entering 60 does not produce a 60-second HTTP timeout. PHP, the web server and the host can still stop work earlier. Do not treat this setting as a hard end-to-end deadline.
Smaller chunks can reduce the size of a failed request, but can also separate context and repeat instructions more often. Use a representative page rather than an arbitrary “fastest” configuration.
6. Assign one WPML job to Lumo
The add-on integrates a local translator identity into WPML. In the reviewed source, its account identifier is lumo_ai_translator; the visible name is the plugin name. That translator needs the appropriate source and target language pairs.
- Open WPML’s Translation Management or Translation Dashboard, depending on version.
- Check its translators section: Lumo AI Translator should be available for the required language pair.
- Select one source page and one target language.
- Follow WPML’s assignment flow, choose Lumo as translator and send the job.
- Open Lumo WP → AI Translator → Queue Status and check that the corresponding job appears.
If the translator is missing, investigate plugin activation, licensing, WPML availability and registration before resending pages. A job assigned to another translator should not be expected to appear in Lumo’s processing queue.
The source listens to job creation as well as assignment. A newly created job can already have its translator set; it does not necessarily pass through a later reassignment action.
For the first page, include a title, two paragraphs, a list, a link and a product code. If your real workload uses Elementor, include an Elementor page too. Plain paragraphs alone do not test a builder workflow.
7. Separate three kinds of success
There are three completion conditions: the provider returned usable text; WordPress and WPML saved it correctly; a reviewer approved what readers see. A completed queue entry cannot replace opening the translated page.
Use the language switcher, check the target URL and compare the rendered result on desktop and mobile.
| Check | Example | Reject when |
|---|---|---|
| Facts | NB-240, 24-month warranty, dimensions | A number, unit, name or promise changes |
| Structure | Paragraphs, lists, headings, buttons | Content disappears or layout breaks |
| Links | Documentation and call-to-action destinations | An invented or incorrect URL appears |
| Language | Terminology, grammar and tone | Fluent wording changes the meaning |
| Metadata | SEO title and description | Fields are wrong or inconsistent with the page |
| Relationships | Language switcher and target URL | The page belongs to the wrong translation group |
The processor contains HTML text extraction, placeholder handling and builder-specific logic. These are useful protections, but they do not prove that every third-party widget or custom field is supported. Check the components your own site uses.
A different design for each language is a separate decision. Our independent Elementor layouts with WPML guide covers that workflow. Translating text and redesigning a translated page are different tasks.
8. Diagnose the failing layer before retrying
| Symptom | Investigate first | Next action |
|---|---|---|
| 401 or 403 | Key, account permissions and endpoint | Verify saved configuration and the provider error |
| Model unavailable | Exact model ID and account access | Choose an available model, save and retest |
| 429 | Rate limits or quota/billing | Read the response; resolve the cause before resubmitting |
| 500, 502 or 503 | Upstream service or gateway | Check service status and use bounded retries |
| Queue stays pending | Assignment and scheduling | Confirm the translator and background processing |
| API succeeded, WPML save failed | Local save/integration | Preserve the job and investigate before retranslation |
| Only part of the page translated | Field extraction and save path | Identify the missing field before changing models |
Our translation queue troubleshooting guide covers pending jobs in more detail.
In the reviewed API method, 429, 500, 502 and 503 can trigger three retries after the initial request, waiting 1, 2 and 4 seconds. This is per-request behavior, not a guarantee about total attempts across a job and later queue runs.
There is also a separate path for reusing a saved, complete translation when the WPML save step fails. That can avoid requesting the translation again in that situation. It does not mean retries can never generate another charge: the provider may have processed a request even if your server timed out before receiving its answer.
For dependable scheduling on a quiet site, open Cron Setup and follow the commands generated for your installation. Coordinate the PHP binary and interval with the host. Keep tokenized processing URLs private, and confirm that a job actually advances. Copying a cron command does not prove it runs.
9. Engineering notes from the source review
Nine isolated PHP checks passed against the supplied 3.20.28 processor. They made no network requests, database writes or license changes. These are narrow adapter-contract checks, not a live translation-quality benchmark or end-to-end compatibility certification.
- Three checks verified header selection for OpenAI, Anthropic and Gemini.
- Three checked response extraction: OpenAI text, Anthropic text after a thinking block, and multiple Gemini text parts.
- Three checked saved-translation reuse: complete WPML-failure data was accepted, partial data was rejected, and an ordinary API failure was not treated as a WPML save failure.
“Translation failed” is too broad to tell you whether another model request is necessary. That is the practical lesson from these checks.
Developers reviewing an update can inspect make_ai_request(), extract_response_content() and get_saved_translation_for_wpml_retry() in includes/class-ai-processor.php, plus job hooks in includes/class-wpml-integration.php. These implementation methods are not a public theme API.
The processor exposes lumoaitr/api/url, lumoaitr/api/request_args and lumoaitr/api/response filters. A private gateway must preserve authentication, request schema and response schema. Redirecting to an arbitrary “compatible” endpoint can expose credentials or return a response the parser cannot read. Use a trusted destination and a separate integration plugin rather than editing vendor files.
The reviewed OpenAI adapter uses Chat Completions, not the Responses API. Compare its contract with the official Chat Completions reference when maintaining a custom integration.
10. Scale based on accepted pages
Before expanding, record the source page, target language, plugin version, model, instruction version, provider usage and reviewer corrections. Keep credentials and private prompts out of shared reports.
A useful cost measure is:
Cost per accepted page =
(API charges + reviewer time cost + correction time cost)
/ pages that passed review
A lower token price does not guarantee a cheaper finished page. A more expensive request can be worthwhile if it needs fewer corrections. Compare configurations on the same pages and language pairs rather than assuming one provider always wins.
Expand to a small group only after the checks pass. Include a long article, a product description and a builder page. Keep important policies and commercial claims under appropriate human review.
Multilingual SEO starts after the API call
The API key itself is not a ranking factor. Useful translated content, accessible language URLs and correct relationships are what readers and search engines encounter.
Check crawlable language URLs, meaningful translated content, working internal links and appropriate canonical/hreflang output. Do not translate every page into every language simply because a bulk button exists. Google’s multilingual-site guidance explains language signals; our multilingual SEO and crawl-budget guide provides a planning checklist.
The workflow is ready to scale when you can explain what was sent, where it was saved, what it cost and why the translated page is trustworthy. Bringing your own API gives you control over that process while WPML manages the multilingual site around it.
Top comments (0)