Getting started

Overview

Phox Translate turns a Breakdance, Oxygen or Bricks site into a multilingual site. It translates your pages, headers, footers, templates, popups, products, menus and SEO with DeepL or OpenAI, and creates real WordPress pages you can edit like any other.

The core idea: every translation is an ordinary WordPress post, linked to its source. There's no proxy, no cloud dashboard and no shortcode soup. Visitors on a translated page get a fully translated experience: the header, footer, templates and popups all swap to their translated variants automatically, post loops show only that language, menus and category labels follow along, and the site locale switches so even WooCommerce checkout strings match.

Getting started

Requirements & installation

1. Install the plugin. In WordPress go to Plugins → Add New → Upload Plugin, choose the phox-translate.zip file and click Install Now.
2. Activate it. A new Phox Translate item appears in the main admin menu.
3. Add your API key. Open Phox Translate → Provider, choose DeepL or OpenAI, paste your key and click Test Connection.
4. Choose your languages. On the General tab set your default language and tick your target languages.

Getting started

Quick start: your first translation

Let's translate one page into French, end to end.

1. Configure once. On Phox Translate → General, set your default language (e.g. English) and tick French as a target. On the Provider tab add your API key and test the connection.
2. Open any page in the WordPress editor. In the sidebar you'll find the Phox Translate box listing your target languages.
3. Click Translate Page. A new French page is created as a draft, linked to the original, with the builder layout intact and every text element translated. The box shows an Edit link per language.
4. Review and publish. Open the draft in the builder if you want to tweak anything, then publish it. Its URL will be /fr/page-name.
5. Add the switcher. Drop the Language Switcher element into your header (search the Breakdance or Bricks element panel), or use the [phox_language_switcher] shortcode. Visitors can now hop between languages.

When you're happy with how one page behaves, use the site-wide wizard to do the whole site in one run.

Getting started

The admin interface

Everything lives under the Phox Translate top-level menu, organised into six tabs:

In the post lists (Pages, Posts, any enabled type) you also get a Language column and a language filter dropdown, so it's always clear which version of a page you're looking at.

Setup

Languages & URLs

Default and target languages

The default language is the language your content is written in. Target languages are the ones you translate into; 33 are supported, covering everything DeepL offers plus additional languages via OpenAI.

URL style

Slugs themselves are translated: an English page at /landscaping becomes /fr/amenagement-paysager, not /fr/landscaping. For languages that don't romanise cleanly (Japanese, Arabic, Russian and so on) the original slug is kept so URLs never come out empty.

Post types

Choose which public post types are translatable. Pages and posts are enabled by default; add WooCommerce products or any custom post type from the same list. Your builder's own template post types are handled on the Globals tab, so they never appear here (which would translate them twice).

Flag overrides

For languages spoken in several countries, choose which flag the switcher shows: 🇺🇸 or 🇬🇧 for English, 🇧🇷 or 🇵🇹 for Portuguese, and so on.

Setup

Translation providers

You bring your own API key and pay the provider directly. Typical cost is pennies per page.

Enter the key on the Provider tab and click Test Connection; DeepL responses include your current usage against your quota.

HTML preservation

Rich text often contains inline HTML (links, bold, line breaks). With Preserve HTML on (the default), DeepL is instructed to translate only text nodes, and OpenAI is prompted to leave tags untouched, so your markup survives translation intact.

Setup

Page builders

There's nothing to configure — Phox Translate detects your active builder on every request and adapts how it reads content and swaps globals. One plugin covers all of the following:

Setup

License

Enter your license key on the License tab and click Activate. An active license enables plugin updates and unlocks the site-wide wizard. Translating individual pages and globals works without a license, so you can evaluate the plugin fully before committing to a bulk run.

Translating

Single pages & posts

Every translatable post gets a Phox Translate meta box in its editor sidebar showing:

• The post's language, and its source if it is itself a translation.
• Existing translations with their publish status and edit links.
• Checkboxes for each missing language and a Translate Page button.

Translations are created as drafts so you can review before anything goes live. The whole builder layout is carried over; only the text changes. Internal links in the content are rewired to the translated versions of the pages they point at, wherever those exist.

Updating a translation

Once a translation exists, translating again skips it by default (your manual edits are safe). To re-translate after changing the source, use the wizard with Overwrite existing translations ticked, or the Re-translate button on globals. Overwriting replaces the translated content, title, slug and excerpt with a fresh translation of the current source.

Translating

Headers, footers, templates & popups

The Globals tab lists every global your builder exposes: on Breakdance/Oxygen that's headers, footers, global blocks (components), templates and popups; on Bricks it's every template in the Bricks template CPT (headers, footers, sections, content and popups). Each row shows a status dot per target language (with draft states flagged), plus Translate and Re-translate buttons.

Translated globals are always published (they're never viewed standalone, and the builder's own managers only list published items). On the front end the correct variant is swapped in at render time based on the page's language, so:

• A French page renders the French header, footer and any matching templates (blog layouts, archives, search results, 404).
• Popups render in French too, whether they fire automatically or from a button, link, form action or interaction.
• Global blocks used as post loop card templates swap as well, so loops on translated pages use the translated card design.

Translating

The site-wide wizard

The wizard translates your entire site in one guided flow. It requires an active license, a configured provider key and at least one target language; it will tell you (with links) if anything's missing.

1. Audit. The wizard scans every enabled post type plus all globals, taxonomy terms and navigation menus, and reports totals, untranslated counts and character counts per type.
2. Select. Untick any content type, or expand a type to exclude individual pages. Taxonomy terms and navigation menus have their own include toggles.
3. Options. Choose the target languages for this run, whether translations are created as drafts or published immediately, whether existing translations are overwritten or skipped, and an optional delay between API requests.
4. Confirm. A summary shows the exact number of jobs, estimated characters and an estimated cost for your chosen provider, before a single API call is made.
5. Run. A progress bar tracks every job. You can watch it, or click Run in Background and close the tab; processing continues server-side via WP-Cron, and reopening the Wizard tab resumes the progress view automatically.
6. Finish. The completion screen lists anything that failed (with the reason and a one-click Retry Failed Items), and walks you through next steps: review drafts, add the language switcher, check the Globals tab.

How the batch behaves

• Without Overwrite, only missing languages are queued per item, so the job count always matches the estimate and nothing you've edited is touched.
• A database lock guarantees each job runs exactly once, even with the tab open and cron running together.
• Each job is only removed from the queue once it succeeds, and memory limits are raised for large pages — so a page big enough to exhaust resources simply retries on the next tick rather than saving blank. After three failed attempts a job is logged and skipped so it can never block the queue.
• After the last job, the plugin re-runs URL and reference fix-ups across all translations so cross-links, global block references and popup references all point at the right language.

Translating

Taxonomy terms

Categories, tags and WooCommerce attribute terms are translated with a display-only overlay. Term names and descriptions are translated once (as part of a wizard run) and stored as term meta; on the front end, pages in another language display the translated name while the term itself keeps its ID, slug and taxonomy.

This design is deliberate: because nothing is renamed in the database, queries can't break. Builder query controls, tax queries, Phox Facets filters and archive URLs all keep matching against the real values, while visitors see translated labels on cards, archives, facets and product pages.

Translated posts also carry the same term assignments as their sources, so category archives and filtered loops return the right posts in every language.

Editing term translations

Every translated name is editable by hand. Open the term's edit screen (e.g. Posts → Categories → Edit) and you'll find a Phox Translate section with a name field per target language (and a description field where relevant). Empty a field to fall back to the original name. Note that re-running the wizard's term pass with Overwrite replaces manual edits with fresh machine translations.

Translating

Navigation menus New

Classic WordPress menus (built under Appearance → Menus) sit outside the builder tree, so — like taxonomy terms — they're translated as a display overlay, with nothing duplicated. Menu item IDs and structure are never touched; only the URL and label a visitor sees are swapped at render time.

• Links follow the language. A menu item pointing at a page or post automatically resolves to that page's translation on a translated page. Custom links are matched against the internal link map and swapped when the target has a published translation.
• Labels translate too. Item labels are translated once (a wizard step, via the include menus option) and stored as item meta. Where a label simply matches the linked page's title, it falls back to the translated title automatically, with no per-item setup.
• Editable per item. Each menu item on the Menus screen gains a Phox Translate labels field per target language, so you can override any label by hand. Empty a field to fall back to the original.

Translating

What gets translated

For each post, the plugin translates:

• The builder tree: every text-bearing property across the element library — headings, rich text, buttons, form labels, placeholders, submit and success/error messages, login form strings, FAQ questions and answers, slider labels, counters, image alt text and ARIA labels. The whitelist ships tuned for both the Breakdance element library and Bricks element keys.
• Post basics: title, slug (translated naturally, then sanitised), excerpt and post content.
• SEO meta: Yoast and RankMath titles and descriptions. Source-language SEO values are never copied verbatim onto translations.
• Custom fields: ACF and Phox Studio text, textarea and WYSIWYG fields, including repeater and group sub-fields.
• WooCommerce products: custom attribute names and values, and purchase notes. Taxonomy-based attributes are handled by the term overlay.

Alongside the text, the plugin also rewires references inside the copied layout: internal links point at translated pages, global block IDs point at translated global blocks, and popup references point at translated popups.

The front end

The language switcher

The switcher lets visitors change language. One renderer powers four ways of placing it, with identical markup and styling:

Options

Smart fallbacks

If the current page has no translation in a given language, the switcher doesn't dead-end. By default it links that language to its translated homepage, so the visitor still lands in a fully translated shell. Fallback links carry a --fallback CSS class if you want to style them differently. A language with no page translation and no translated homepage is simply omitted.

// Shortcode examples
[phox_language_switcher]
[phox_language_switcher style="flags"]
[phox_language_switcher style="inline" show_current="0" missing="hide"]

The front end

How pages are served

When a visitor lands on a translated page, several things happen automatically:

• Globals swap. The header, footer, matching templates and popups are exchanged for their translated variants before rendering — via Breakdance's controller, or the bricks/active_templates filter on Bricks.
• Queries are scoped. Archives, search results and post loops for translatable post types only return posts in the current language. On default-language pages, translated variants are hidden. Loops can opt out with the pt_skip_lang_filter query var.
• The locale switches. The plugin calls switch_to_locale() to match the page language, so WordPress core, WooCommerce and other plugins render their own strings (checkout, dates, validation messages) in the right language, provided the relevant language packs are installed.
• Terms & menus overlay. Category, tag and attribute names, and navigation menu labels and links, all display in the current language.
• Search stays in language. Search forms on translated pages carry a language marker, so results and the search results template stay in the visitor's language, including Phox Elements search bars with facet parameters.
• Facets stay in language. Phox Facets refreshes are language-scoped, so filtered loops, counts and ranges match the page's language.

The front end

SEO

• hreflang. Every published page in a language group outputs <link rel="alternate" hreflang="…"> tags for its siblings, plus x-default pointing at the source language.
• Translated SEO meta. Yoast and RankMath titles and descriptions are translated; canonical URLs and source-language values are never duplicated onto translations, avoiding duplicate-content signals.
• Clean URLs. Prefix (/fr/page-name) or suffix (/page-name-fr) structures, with translated slugs.
• Hub pages are noindexed and kept out of search and listings.
• Real pages. Because translations are ordinary posts, they're crawled and indexed like any other page. No JavaScript translation, no cloaking.

Advanced

Advanced settings

Advanced

Repairs & self-healing

Opening the Globals tab doubles as a repair pass. Each visit silently runs a set of idempotent fix-ups (they write only when something is actually wrong):

• Publishes any global translation stuck as a draft.
• Repairs builder meta on translated posts (template settings, conditions) if a copy was ever corrupted, and strips display conditions from translated Bricks templates.
• Re-copies taxonomy term assignments from sources to translations.
• Re-runs the global block / popup ID swap and the internal URL swap across every translation.

---

Developer reference

Data model

Translations are ordinary posts of the same post type as their source, linked by post meta. Nothing is stored outside your database, and deactivating the plugin leaves every translated page in place.

Developer reference

REST API

Endpoints live under the phox-translate/v1 namespace.

Developer reference

Builder facade

All builder differences are resolved by a small facade of functions in phox-translate.php. Everything else — linking, hreflang, query scoping, the switcher, terms, menus and the wizard — is builder-agnostic and sits on top of it. Supporting a new builder (Elementor, Divi, etc.) is mostly a matter of implementing this seam.

Developer reference

Hooks, query vars & template tags

Template tags & helpers

// Echo the language switcher anywhere in a theme.
pt_language_switcher( [ 'display_style' => 'inline' ] );
// Current page language ('fr') and the site default ('en').
$lang    = pt_get_current_page_language();
$default = pt_get_default_language();
// Published translation URLs for a post: [ 'en' => url, 'fr' => url ].
$urls = pt_get_translation_urls( $post_id );

Filters

// Change the locale used on translated pages (default maps 'fr' to 'fr_FR' etc).
add_filter( 'pt_switch_locale', function ( $locale, $lang ) {
    return $lang === 'fr' ? 'fr_CA' : $locale;
}, 10, 2 );

Query vars

---

Help

Troubleshooting

The wizard button is greyed out

The wizard needs an active license, a working provider key and at least one target language. Warnings above the button link to whichever tab needs attention.

A translated global isn't showing in the builder's own manager, or a translated page shows an English popup / link / card

Open the Globals tab once. It runs the full repair pass, which fixes stray drafts, re-points references and re-swaps URLs across all translations. Then hard-refresh the front end.

A translated Bricks page or template renders blank

The content saved empty. Call the diagnose endpoint on the source — all_string_leaves_count shows whether there's text on the key being read. Remember a Bricks template keeps its text in the header/footer/content areas, not a single content key.

A loop or archive shows posts from both languages

Language scoping applies to queries for the post types enabled on the General tab. Check the post type is ticked there, and that the loop's query targets that type explicitly. A custom query can opt in with pt_filter_lang.

Checkout or date strings are still in the default language

Locale switching relies on WordPress language packs. In Settings → General, temporarily switch the site language to the target language once; WordPress downloads the core (and WooCommerce) translation files, after which you can switch back.

Some element text wasn't translated

The element probably stores that text under a property key not in the whitelist, common with third-party elements. Call the diagnose endpoint for the page, find the key holding your text in all_string_leaves_sample, add it to Text keys on the Advanced tab, and re-translate with Overwrite.

Menu links or labels are still in the default language

Confirm the linked pages have published translations, and run the wizard's include menus step (or set per-item labels on the Menus screen). Custom links are matched by URL, so they translate only once the target page has a published translation.

The batch seems stuck

Background progress relies on WP-Cron, which advances when the site gets traffic. Reopen the Wizard tab: every progress poll also processes a job and re-arms the background worker. Persistent failures appear on the completion screen with reasons and a retry button; the most common cause is an exhausted provider quota.

The switcher renders nothing

The switcher needs at least two languages with somewhere to link. Check target languages are configured and the homepage is translated (it's the fallback target for untranslated pages).

Help

FAQ

Which builders are supported?

Breakdance, Oxygen (6+) and Bricks are detected automatically, and plain WordPress content is translated too. On a vanilla site you still get post/SEO/custom-field translation, language-scoped queries, hreflang and the shortcode switcher. With a builder you add full element-tree translation and automatic header/footer/template/popup swapping.

Can I edit a translation by hand?

Yes, that's the point. Translations are ordinary posts; open them in the builder or the editor and change anything. Manual edits are preserved unless you deliberately re-translate with Overwrite.

What does it cost to translate my site?

Whatever your provider charges, nothing more. The wizard shows a character count and cost estimate before starting. DeepL's free tier (500,000 characters per month) covers a typical small site in full.

What happens if I deactivate the plugin?

Every translated page remains published at its URL. You'd lose the automatic global swapping, query scoping, hreflang and switcher until you reactivate, but no content is ever removed.

Will translated categories break my product filters?

No. Term translation is a display overlay; IDs, slugs and taxonomies are untouched, so queries, facets and archives keep working exactly as before. Menu translation works the same way.

Do I need a separate menu per language?

No. Keep a single menu in Appearance → Menus — Phox Translate overlays translated labels and links per language automatically.

Can search work per language?

Yes. Searches made from a translated page carry a language marker, return results only in that language, and render through the translated search results template.

Is my API key safe?

It's stored encrypted with a random IV per encryption, never displayed back in full, and only ever sent to your chosen provider over HTTPS.

Help

Changelog

3.3.0

New

• Bricks support. Bricks is detected automatically alongside Breakdance and Oxygen. Bricks pages and templates translate — including a template's separate header, content and footer areas — and headers, footers, sections and popups swap language on the front end through Bricks' native bricks/active_templates filter.
• Bricks language switcher element. A native "Language Switcher" element for the Bricks builder, sharing the same renderer and options as the Breakdance element and shortcode.
• Navigation menu translation. WordPress menu item labels and links follow the current language via a display overlay — a single menu serves every language. Labels are translated as a wizard step and stored as item meta, with an editable field per language on the Menus screen; links resolve to each target's translation automatically.

Improved

• The site audit and wizard now include navigation menus as their own optional step, with character counts folded into the cost estimate.
• The text-key whitelist gained Bricks element keys (subtitles, option labels, separator and submit-button text, marker and info text, price prefixes/suffixes, ribbon text and more), merged into existing installs automatically.
• Translated templates have their display conditions stripped per builder (Breakdance condition removal and Bricks templateConditions), so a translated template never competes with its source.
• The Globals tab repair pass now also re-strips Bricks template conditions when it re-copies builder meta.

Fixed

• Bricks content is written back with correct slashing, so translated Bricks pages and templates stay valid and keep appearing in Bricks' own template manager.
• Front-end query scoping, term overlays and facet refreshes now resolve language correctly under Bricks as well as Breakdance/Oxygen.

3.0.0

New

• Taxonomy term translation. Categories, tags and attribute names display translated via a safe overlay that never touches slugs or queries, with per-language fields on the term edit screens for manual polish.
• Language switcher everywhere. New [phox_language_switcher] shortcode and pt_language_switcher() template tag alongside the Breakdance element, all sharing one renderer.
• Smart switcher fallbacks. Untranslated pages link to that language's homepage instead of showing "no translations", with a per-element choice to hide the language instead.
• Popup support. Breakdance popups are audited, translated and swapped per language, including popups opened from links, forms and interactions.
• Locale switching. Translated pages switch the WordPress locale so WooCommerce and core strings follow the page language.
• Language-aware search. Searches from translated pages return results in that language through the translated search results template.
• Wizard upgrades. Preflight configuration checks, per-type and per-item selection, provider-aware cost estimates, background resume when reopening the tab, a completion screen with per-item errors and one-click retry, and taxonomy terms as an optional batch step.
• Top-level admin menu with a translation icon.

Improved

• Massively expanded text coverage: form messages, login strings, image alt text, ARIA labels, FAQ answers, sliders, counters and more, merged into existing installs automatically.
• Translated posts now carry their source's taxonomy term assignments, so archives and Phox Facets filters work in every language.
• Post loops and archives are language-scoped on initial render, matching facet refreshes.
• Global blocks used as post loop card templates swap per language, and internal URL rewiring covers custom link keys such as header logo links.
• SEO meta, custom fields and WooCommerce translation are now on by default.
• The Globals tab acts as a one-click repair pass for statuses, references, term assignments and URLs.

Fixed

• Translated globals no longer disappear from Breakdance's template and popup managers.
• Copied Breakdance meta (template settings, conditions) survives intact; existing installs are repaired automatically.
• Translated templates no longer compete with their sources in Breakdance's condition matching.
• The switcher element renders correctly in the builder when settings change.
• Overwrite mode re-translates excerpts; the excerpt is no longer skipped.

Security

• Per-post capability checks on translation endpoints, license checks on all wizard endpoints, server-derived wizard job lists, stronger API-key encryption with per-encryption IVs, and draft URLs removed from the public translation-URLs endpoint.