Complete WP-Translate documentation
From first installation to technical reference: all features explained, step by step, on a single page with an index to jump to what you're looking for.
What is WP-Translate
WP-Translate turns your WordPress into a multilingual site without leaving the frontend. You open your own page in the language you want, click on the text you need to change, and edit it while looking at the real design, so a translation never breaks a button or a headline.
You don't need an account, API key, or registration: it installs and works. A free integrated translation engine translates from the first minute, and you can connect your own DeepL, Google, Gemini, or Yandex key whenever you want.
Visual translation on your own website, with the context in front of you.
Each language published on its own URL, indexable by Google.
Everything is saved in your database: the visitor is served normal HTML, without calls to any API.
Installation and activation
Install it like any other WordPress plugin: upload the ZIP file from Plugins → Add New → Upload Plugin, or copy the folder to /wp-content/plugins/. Then activate it from the menu of Plugins.
Requirements: WordPress 6.1 or higher and PHP 8.0 or higher.
No need to touch the database: upon activation, it automatically creates its own tables.
If you update from a previous version, the new tables are created automatically on the first load after the update.
The free engine requires no configuration. You can translate your first language without creating any account or entering any API key.
The setup wizard
The first time you activate the plugin, a guided wizard appears that gets you ready to translate in four steps. It's the fastest way to get the site configured without going through all the settings manually.
The four steps
1. Welcome. A summary of what you will achieve.
2. Source language. You confirm what language your site is currently written in.
3. First additional language. You choose the language you want to translate to; it is created with its URL prefix.
4. Translation engine. You stick with the free engine or paste your DeepL/Google/Gemini/Yandex key, and the first site scan is launched.
You can reopen it anytime from the "Wizard" link in the plugin row, on the Plugins screen. It doesn't delete anything already configured.
Add your first language
In WP-Translate → Languages you define the main language (the one your site already has) and add the target languages. Each additional language is published under its own URL prefix —for example /en/ o /fr/— with its reciprocal hreflang tags.
The main language marks from which text everything else is translated.
Each target language has its code, its flag, and its URL prefix.
You can activate or deactivate a language without losing what has already been translated in it.
The free version publishes your main language plus one additional language. With a license, languages are unlimited.
Visual editor on the frontend
It's the heart of the plugin. You open any page of your site in the language you are translating and enter edit mode from the toolbar. From there, every text on the page is clickable: headlines, buttons, menus, image texts. When you click, a side panel suggests the automatic translation, and you adjust it.
You translate while looking at the final design: you instantly see if a long text misaligns a button.
The panel suggests the engine's translation and lets you correct it before saving.
You change languages from the bar itself to check how each version looks.
Access to the editor is in the WordPress admin bar when you visit your website logged in. Only users with permission to edit the site can see it.
Full site scan
Instead of going page by page, the scan extracts all translatable strings from your posts and pages at once and makes them ready in the string manager. This way you can translate them in bulk without having to open each one in the visual editor.
Detects the actual text of each content, including that generated by builders.
It's idempotent: rescanning does not duplicate already registered strings.
Gathers all pending work in a single place for batch translation.
Full site scanning is a feature of the licensed version. In the free version, you translate with the visual editor and with batch translation of what has already been detected.
Batch translation
With one click you send all pending strings for translation. The queue works in batches, resumes where it left off if interrupted, and never translates the same string twice, because it first consults the translation memory.
Processes in batches to avoid saturating the server or the engine.
Resumes automatically: if you close the tab, it continues where it left off when you return.
Shows real progress and how many strings remain per language.
The free version translates in batches of 10 strings; with a license, batch translation is complete.
String manager
The string manager is the central list of all your site's text and its translation status in each language. From here you filter, search, and decide what is translated and how.
Translation statuses
| Status | What it means |
|---|---|
| Pending | The string exists but does not yet have a translation in that language. |
| Automatic | Translated by the engine, still not reviewed by a person. |
| Manual | Written or corrected by hand. Automatic translation never overwrites it. |
| Reviewed | Marked as checked and final. |
When a translation is manual or reviewed, no automatic process overwrites it. It's a way to «fix» a text —for example, your brand name— so that a batch translation doesn't change it.
Translation memory
Each translated string is saved in your own database. If the same phrase appears on two hundred pages, the engine is called only once and the other one hundred ninety-nine reuse that translation.
Saves engine calls and, therefore, cost and time.
Maintains consistency: the same phrase is translated identically across the entire site.
It's yours: if you ever remove the plugin, you can export your translations beforehand.
Translation engines
You choose the engine in Settings → Translation Provider. The free engine works without any key; paid ones use your own API key and you are billed directly by the provider.
| Engine | Key | Notes |
|---|---|---|
| Free (by default) | No | Translates without configuration. Uses Google's public endpoint and, as a backup, MyMemory. |
| Google Cloud Translation | Your key | Google Cloud quality and quota, billed to your account. |
| DeepL | Your key | Very good quality in European languages. |
| Google Gemini | Your key | AI translation; processes multiple strings per call. |
| Yandex Translate | Your key | Alternative with good language coverage. |
A request is sent only when you actively translate a string or launch a batch, and it contains only the text to be translated and the language code. While a visitor views already translated pages, no external service is contacted.
Change engine without losing anything
You can change engines at any time without losing what has already been translated. The text already in your database is preserved; the new engine is only used for translations you request from that moment on.
Start with the free engine and switch to DeepL or Gemini when you want more quality.
What has already been translated remains as is; only new content uses the new engine.
You can retranslate a specific string manually if you want to redo it with the new engine.
URLs by language
Each additional language is published under its own URL prefix. The translated version is not a parameter or a layer on top: it is a real address that Google can crawl and index as an independent page.
Clean structure by prefix: tusitio.com/en/…, tusitio.com/fr/….
The main language remains at the root, without a prefix.
Slugs can be translated so that the URL is also in the target language.
hreflang, canonical, and sitemap
For Google to understand that each URL is the version of the same page in another language, the plugin automatically adds the signals required by the search engine.
Reciprocal hreflang tags between all language versions of each page.
Self-referencing canonical in each language, so they are not marked as duplicate content.
Sitemap by language, so that the search engine discovers all versions (licensed feature).
Yes. By being published under its own URL, with reciprocal hreflang and its own canonical, each language is independently indexable.
Language selector (switcher)
The selector allows the visitor to change language. It is available in four forms, so that it fits anywhere without touching code.
| How to insert it | Where it is used |
|---|---|
Shortcode | In any content, page, or text. |
| Theme Widget | In sidebars and classic widget areas. |
| Menu item | As another entry in your navigation menus. |
| Elementor Widget | By dragging it in the Elementor editor. |
Various styles: dropdown, list, flags, or inline.
Shows flag and name, or only flag, depending on what you prefer.
Compatibility
WP-Translate works with what you already have set up, without special templates or fragile configurations.
Any theme. It does not depend on the theme to detect or serve translations.
Elementor and Elementor Pro. It reads designs from their own internal format, so not even the text of Elementor Pro widgets escapes.
WooCommerce. Covers product texts and shop pages.
Common cache plugins. As each language is served as normal HTML, it coexists with caching.
With a license, the plugin can also translate outgoing emails (WordPress and WooCommerce notifications) to the recipient's language.
Settings panel
Everything that is not text translation is controlled from WP-Translate → Settings: the active engine and its key, the behavior of the switcher, and advanced options such as translate on save.
Translation provider and API key (if you use a paid engine).
Translate on save: when you edit a post, its changes are automatically translated (licensed feature).
Translated meta title and description for the SEO of each language (licensed feature).
What each version includes
The free version is fully functional for one site with an additional language. The license lifts the limits and adds scaling features. The essentials are never limited: the visual editor, the selector, URLs per language, hreflang, canonical, and serving what has already been translated always work.
| Feature | Free | With license |
|---|---|---|
| Additional languages | 1 | Unlimited |
| Engine | Free Google | Gemini, DeepL, Google and Yandex |
| Automatic quota | 500 strings/month | No limit |
| Batch translation | Batches of 10 | Complete |
| Scan the entire site | — | Yes |
| Translate on save | — | Yes |
| Translated meta title and description | — | Yes |
| Sitemap by language | — | Yes |
| WordPress and WooCommerce Emails | — | Yes |
A site that loses its license continues to function and does not lose languages: it only loses access to paid features. What has already been translated continues to be served.
License and updates
The license is for life (one-time payment, no renewal). What defines each plan is the number of sites on which you can activate it, not an expiration time.
You paste the key on the license screen and the paid features are unlocked, without reinstalling or losing translations.
Plugin updates arrive on your WordPress dashboard like those of any other plugin.
You can release a site to move the license to another installation within your site limit.
Technical reference
For more technical profiles, these are the integration points that the plugin exposes at a usage level. There is no need to touch code to use the plugin; this section is only for those who want to integrate it precisely.
Shortcodes
| Shortcode | What for |
|---|---|
| Insert the language selector into any content. |
Elementor Widget
The language selector is available as a native Elementor widget: it is dragged to the design and its style (dropdown, list, flags or inline) is configured from the editor itself.
REST API
The plugin registers its operations under its own WordPress REST API namespace (wptm/v1). The routes are protected by WordPress administration permissions: only an authorized user can launch scans or translations. The internal detail of each route is part of the plugin's operation and is not necessary for using it.
Where everything is saved
All translations live in their own tables within your WordPress database, not in an external service. This is what makes serving a language not dependent on any API and ensures that the translations are yours.
Translations and their status (automatic, manual, reviewed) are saved per string and per language.
The translation memory avoids calling the engine again for a repeated phrase.
Upon uninstalling, the plugin asks if you want to keep or delete its tables.
The internal logic —how it detects strings, how it rewrites URLs or how it signs requests— is part of the product and is not documented here. This guide covers everything you need to use it and get the most out of it.
Troubleshooting
The most common questions, answered.
Ready to translate your site?
Install WP-Translate and have your first language published in minutes. No key to start.