Hooks Reference

Defaults to [ 'wp_block', 'wp_navigation', 'wp_template', 'wp_template_part' ] - synced patterns, block-theme navigation menus, and block templates and template parts.

This is a curated allowlist, not get_post_types( [ 'public' => false ] ): a checkbox is only offered for a type PerfLocale can actually serve a translation for. wp_template and wp_template_part are in the default list but are not shown as individual checkboxes - they are switched on together by the separate Full Site Editing setting, so removing them here puts them beyond that setting's reach too. See Full Site Editing.

Note: this list controls the settings UI only. It is separate from perflocale/translatable_post_types, which also governs language filtering of ordinary content queries.

A context is an identifier meant for code (blogname, attribute_label_size), but it is shown to an operator, so a domain that knows a friendlier name can supply one.

PerfLocale uses this itself to show Site Title and Tagline instead of blogname and blogdescription. Always scope your callback to your own domain, or you will relabel another plugin’s identically-named context.

Use it when a post type’s editor is not WordPress’s own - a form builder, a page builder - or return an empty string to render no link at all.

Why this exists: get_edit_post_link() builds from the post type’s _edit_link, which WordPress only populates for types registered with show_ui. Contact Form 7 forms, WPForms forms and WooCommerce variations are all registered without it, so core returns null for exactly the objects a translation screen most needs to link.

Contract - read this before shipping a callback:

• Return a string. An absolute http(s) URL with a host, or ''. A Stringable object is accepted and converted. Anything else - array, object, null, false - is discarded and treated as ''.
• Relative URLs are rejected. A relative href resolves against whatever admin page the user is on, so it looks like a working link and goes nowhere. '' is always the safer answer.
• IDs are current-blog. A bare integer has no network-wide identity; on multisite, switch_to_blog() before resolving.
• Pass through what you do not own. Check $post_type first and return $url unchanged otherwise. Later callbacks see your return value, and returning a non-string can raise a TypeError inside another integration’s typed callback.
• Exceptions are not contained. A callback that throws, or a Stringable whose conversion throws, propagates as WordPress normally would. Only the final value is validated.
• This resolves a URL. It does not authorize anything. PerfLocale still applies its own capability checks, and the value is escaped at every HTML sink. A non-empty URL is not permission.

Use it for a post type that is not publicly_queryable but is still reachable.

Why this exists: get_permalink() returns a URL for a non-viewable post type too - one that 404s - so an emptiness check cannot tell a live link from a dead one. PerfLocale gates on is_post_type_viewable() instead. That is correct for form post types and wrong for a WooCommerce variation, whose permalink resolves to its parent product and returns HTTP 200; the bundled WooCommerce integration restores it through this filter.

The same return contract applies as above: an absolute http(s) URL with a host, or ''.

Backed by the persistent perflocale_gc_protected_domains option, so an addon's protection survives its own deactivation.

Higher = fewer queries, more peak memory per batch. Clamped to 100-10,000.

Default 20,000.

The check writes a short-lived random file into wp-content/uploads/perflocale/exports/, requests it over HTTP, and deletes it either way; the verdict is cached for an hour, and an inconclusive result for fifteen minutes.

Return false on a host where loopback requests are blocked and transients do not persist - the combination where the probe would repeat its timeout on every Site Health load without ever learning anything. Disabling it skips only the measurement: the check still appears and still tells you to add the server rule, because a filter should never be able to make a real exposure look green. If you turn this off, verify the rule yourself - see Security.

Defaults to true when any menu location is selected on the Language Switcher settings tab; a filter can force it per menu.

Default is the language row’s date_format field if set, else the WP date_format option. Lets a theme/addon override per-language without saving to the language row.

The $context argument says what is being asked - so the same site can fall back differently for, say, front-end rendering than for hreflang output. Whatever the filter returns is put back through the same guardrails as the stored setting (unknown slugs dropped, self-references removed, length capped), so a malformed return cannot corrupt resolution.

Use this when the decision depends on the language being resolved rather than on the whole map. As with the map filter, the returned chain is re-validated, so guardrails still apply.

The bundled ACF, Meta Box and Pods add-ons use this filter to keep the values of the source’s password fields out of a new translation: ACF password fields at any depth (inside groups, repeaters, flexible content and clones), Meta Box password fields stored as post meta of their own, and Pods password fields. A Meta Box group is one meta row holding all its sub-fields, so the Meta Box add-on also listens to perflocale/translation/created and rewrites each copied group row without its password sub-fields, in nested groups and every clone too; the other values of the row stay as copied. When content sync later seeds a group into a translation that has no row for it, the add-on takes the same sub-fields out through perflocale/sync/seed_meta_value.

The default of 60s covers most real-world inserts including a meta + featured-image copy step that runs synchronously. Sites with slow save_post integrations (heavy SEO plugins, image regeneration on insert) can extend this so a legitimately-long insert doesn't lose its lock mid-flight.

Default is shorter (30s) because terms have no meta/image copy step.

Built-in field keys: featured_image, menu_order, post_parent, post_date, post_author, comment_status, ping_status. Each of these is compared against the translation's current value first, and the translation is written only if something actually differs - so a save that changes nothing synced fires no save_post for the translations and leaves their modified dates alone. When a translation is written, only the synced columns and its modified date change: its content, title, excerpt, status and publish date (unless post_date is synced) stay as stored, whoever saves, and its save hooks run as for any save. When a synced post_parent moves a translation to another parent, WordPress makes its slug unique among the new parent’s children (for example by adding -2); any other write keeps the stored slug. The perflocale/cache/flush_object purge signal still fires for each translation. Any other value is treated as a meta key: rows are read with get_post_meta() and written row by row with delete_post_meta() + add_post_meta(), so multi-value meta survives.

The callback receives the SOURCE post id so it can read the real row structure and append the remaining rows’ keys. PerfLocale’s bundled ACF addon uses this hook.

That is a publish in a cron run, or outside WP-CLI in a request of nobody logged in or of a user who may not edit the post. The publish then writes Sync Fields, and a changed post password, only to the translations this user may edit, as a save by that user would; 0 writes them to every translation. The default is the post author when the author may edit the post, otherwise 0. See Scheduled posts in the Sync Fields docs.

Runs once per such publish that syncs Sync Fields or copies a changed password: not for a post without translations or opted out of sync, and for Sync Fields not for a translation that Sync Fields marked Needs Update. A return that is not an integer of 0 or more leaves the default.

When a translatable term is edited, PerfLocale mirrors its parent onto every linked sibling - mapped into the sibling’s own language, so a German child points at the German parent rather than at the English parent’s term_id (which would orphan it cross-language). Name, slug, and description stay translator-owned and are never synced.

Return false to leave one sibling’s hierarchy alone while the rest keep mirroring - useful for a market that runs a deliberately flatter catalogue. The filter is only reached when the Sync Term Hierarchy setting (sync_term_hierarchy, default on) is enabled: that setting is the all-or-nothing switch, this filter is the selective one. It is also skipped when the edited term’s parent has no translation in the sibling’s language - PerfLocale leaves the sibling untouched rather than guess a cross-language parent.

Bundled addons (Yoast, ACF, page builders) use this hook to register their own meta keys; your custom plugin can do the same.

Default true. Returning false suppresses the metabox without disabling the frontend featured-image swap (existing per-language overrides keep working) - useful for themes or addons that render their own featured-image surface and want to host the language overrides inside that UI instead. Only consulted for post types that support thumbnails and when the active theme declares post-thumbnails support.

Defaults to PerfLocale’s already-filtered active-language list. Lets a theme or addon drop languages (for example hide RTL languages when the theme ships no RTL stylesheet) or, by returning the full unfiltered list, show every active language regardless of the default filtering.

Bots that match are exempted from the three automatic redirect paths - browser-language, edge-hint, and geo-IP - so they always see the URL they crawled. (Cookie-based detection is unaffected: those redirects already stand down for any visitor who has a perflocale_lang cookie.) The default pattern matches these case-insensitive, word-bounded tokens: bot, crawl, spider, slurp, mediapartners, googlebot, bingbot, yandex, baidu, twitterbot, applebot, facebookexternalhit, linkedinbot, duckduckbot, gptbot, slackbot, discordbot, telegrambot, petalbot, ahrefsbot, semrushbot, pinterestbot, oai-searchbot, chatgpt-user, claudebot, claude-web, claude-user, claude-searchbot, anthropic-ai, perplexitybot, perplexity-user, ccbot, bytespider, amazonbot, meta-externalagent, meta-externalfetcher, duckassistbot, mistralai-user, cohere-ai, diffbot - classic search and social crawlers plus the AI crawlers and assistant fetchers (OpenAI, Anthropic, Perplexity, Common Crawl, ByteDance, Amazon, Meta, DuckDuckGo, Mistral, Cohere, Diffbot), which index for AI search and answer engines and mis-index a language redirect exactly like a classic engine. Compound names are enumerated explicitly because \bbot\b sees a letter-letter boundary inside “googlebot”. Return an empty string to disable bot exemption entirely.

Return false to disable that redirect and let both forms resolve.

When “Hide URL prefix for default language” IS enabled, / is canonical, but the still-prefixed default-language home (e.g. /en/) also resolves to the same homepage - a duplicate-content URL. The plugin 301-redirects that bare /en/ back to the canonical /. This redirect is home-only: inner prefixed URLs such as /en/contact/ are left untouched (their per-page canonical tag already de-duplicates them). Return false to disable it and let both / and /en/ resolve. GET/HEAD requests only.

One of subdirectory, subdomain, domain, or query - the last being the ?lang= query-parameter mode that works with every permalink structure (including Plain) on any server; the default language always keeps clean, param-free URLs. MUST return the same value for every call within a site - every generated link, rewrite rule, and cached URL assumes one mode per site. Vary it per environment or per blog, never per request. Unknown values fall back to the stored setting.

The default is lang, which is a generic name another plugin, theme, or page builder may already own - leftover Polylang installs are the common case. Renaming it moves PerfLocale out of the way without touching rewrite rules by hand: the URL writer, the language detector, and the generated rewrite rules all read this one value, so they cannot disagree.

The returned value is passed through sanitize_key(), and an empty or non-string return falls back to lang, so the result is always a safe query-argument name. The filter fires once per request (once per blog on multisite) no matter how many URLs the page builds, so it is not on any hot path.

Register this from an mu-plugin. The name is resolved while PerfLocale itself loads, because query-mode language detection has to read the request before plugins_loaded fires. A filter added from an ordinary plugin or from a theme’s functions.php runs too late and is ignored - silently, since there is nothing to warn about at that point. Files in wp-content/mu-plugins/ load first, so that is the supported home for it.

Renaming this is a URL change, not a cosmetic one. Existing links carrying the old name stop resolving, and in subdirectory mode the name is baked into stored rewrite rules - flush permalinks (Settings › Permalinks) after adding or changing the filter. Return the same value for every call within a site.

Use it to add, remove, reorder, or mutate entries.

Dev-mode guard: if a filter callback returns a non-array, PerfLocale emits a _doing_it_wrong() notice and falls back to the unfiltered tag list - hreflang output is preserved.

Each ?paged=N archive request caches its own computed hreflang HTML; the default 12 * HOUR_IN_SECONDS balances rebuild cost against reflecting a translation change within half a day if a narrow per-post flush is missed. Singular posts are kept fresh by the per-post invalidator regardless of this value.

Cleaner than walking the whole tag array when you only want to redirect search engines to a language-picker landing page or a specific regional variant. Return an empty string to suppress the x-default entry for the current request.

When the filter returns true, hreflang emits a tag for every active language - even those without an explicit translation of the current post - as long as the language URL would render 200 (i.e. missing_translation_action is show_default or the language has a non-empty fallback chain). Filter value wins over the admin toggle, so addon or theme code can force the inclusive mode without touching settings.

The default decision is computed from the seo_sitemap_source setting:

• core - always inject into WP core sitemap, even when an SEO plugin is also active.
• plugin - never inject into WP core (let the SEO plugin's addon handle alternates exclusively in its own native sitemap).
• auto (default) - skip core when an SEO plugin (Yoast / Rank Math / AIOSEO) is detected via setting or runtime constant/class. Otherwise inject into core.

This filter lets sites with unusual sitemap setups (e.g. a third-party sitemap plugin PerfLocale doesn't recognise, or a Yoast sitemap that has been disabled at the Yoast settings level) override the auto-detection.

The default is page-proportional: wp_sitemaps_get_max_urls() × the number of active languages (counted as at least 2) - i.e. the most a single sitemap page can actually consume, rather than a flat multiple of the page size. Whatever the filter returns is floored at 2,000, so you can raise the cap but not lower it below that. Selections above the cap skip bulk priming and fall back to per-entry lookups - output is identical either way.

Default is the current language’s locale field normalised to hyphen-form (e.g. de_DE → de-DE); return an empty string to suppress the header on this request.

The default block opts in to automatic navigation transitions with a 240ms crossfade AND includes a @media (prefers-reduced-motion: reduce) guard that zeros the animation duration for users with the OS-level reduced-motion preference (navigation still completes instantly - only the crossfade is suppressed). Returning '' disables output entirely. If you override the default, keep the reduced-motion guard in your replacement CSS to preserve WCAG 2.1 SC 2.3.3 compliance.

Useful when a theme runs its own GSAP/slider animations on navigation that would fight the browser transition.

On WP 6.8+ use Core’s wp_load_speculation_rules action instead; our rule is registered via that API and is no longer filterable through this hook.

Useful for pages where prerendering the switcher target would waste bandwidth - paginated archives with heavy media, or URLs that trigger non-idempotent GET side effects.

Return false from this filter to force the fallback self-emit path instead - a standalone <script type="speculationrules" id="perflocale-speculationrules"> emitted at wp_footer priority 20. Primarily useful for integrators who want the perflocale/prerender/rules filter (fallback-path only) to remain active on modern WP, or for test environments exercising the fallback code without downgrading WordPress.

The same path can be forced globally by defining the PERFLOCALE_FORCE_SR_FALLBACK constant - the filter is a per-request escape hatch, the constant is a site-wide switch.

Fires only when fallback is already detected; use this to exempt specific post types or IDs. The guard applies to both explicitly-linked default-language posts AND posts that have no translation-link entry (treated as default-language, matching the plugin-wide convention), so pages authored before PerfLocale was installed are protected too.

Default is div; use span for themes that render the content in an inline context where a block-level wrapper breaks layout. Must match /^[a-z]{1,8}$/ - invalid values fall back to div.

Dev-mode guard: a non-string return triggers _doing_it_wrong() and the renderer falls back to the unfiltered HTML.

Add analytics data-*, inject rel / title, override hreflang / lang / dir, or append additional CSS classes without forking the template.

Values are escaped via esc_attr() (or esc_url() for href). Boolean true emits an HTML boolean attribute; false / null omits the attribute entirely. Attribute names are sanitized to [A-Za-z0-9:_-].

Base attributes the switcher already sets on each option (the filter is your chance to add to or override them):

• href - Target translation URL.
• class - Per-renderer (perflocale-dd__option, perflocale-switcher-block__item, …).
• hreflang - Target language slug.
• lang - Target language slug. Lets screen readers pronounce "Français" / "العربية" with the right phonemes since the option label is in the target language, not the page language.
• dir - rtl when the target language's text_direction is RTL; omitted otherwise. Lets RTL labels render right-to-left even on an LTR page.
• role, tabindex, aria-selected - Set only on dropdown options for listbox semantics.

Dev-mode guard: a non-array return triggers _doing_it_wrong() and the renderer falls back to the built-in attribute map for that option.

Three built-in styles ship - single (one down chevron, the classic native-select look, default), double (stacked up + down chevrons), none (empty string). The filter fires AFTER the built-in lookup so it can substitute markup for any style key, including none - useful for themes that want to inject an icon even when the user picked "no icon" in Settings → Language Switcher.

Returned HTML is sanitized through kses_switcher() at every echo site - if your markup uses tags or attributes outside the switcher's built-in allowlist (e.g. <i> elements, data-* attributes, additional SVG tags), extend the allowlist via perflocale/switcher/kses_allowed_html below. Returning a non-string falls back to empty.

Useful for region groupings, search inputs, recently-used pickers, "Powered by …" notices, or any other panel chrome.

Items injected here are NOT options, so they should not carry role="option". Put non-interactive chrome inside a <div role="presentation"> so the parent listbox doesn't announce it as an option. Returned HTML is sanitized through kses_switcher() - extend the allowlist via perflocale/switcher/kses_allowed_html if your markup needs more.

Same sanitisation, parameters, and role guidance as panel_before above.

Wraps the flag + label by default; the filter lets integrators inject region badges, mixed-direction <bdi> wraps, custom icons, script-tag indicators, etc., without forking the renderer. The same hook fires from both the dropdown and the inline / simple / list paths, so a single callback covers every option surface.

The filter return is passed through kses_fragment() (the switcher's internal kses helper, same allowlist as kses_switcher()) before being concatenated into the output, so unsafe HTML in a filter callback is stripped on every render path - including the Gutenberg block render path, which WordPress doesn't otherwise sanitize. Tags / attributes outside the built-in switcher allowlist (e.g. <bdi>, <i> icon-font glyphs, data-*) must be permitted via perflocale/switcher/kses_allowed_html.

Needed when a custom arrow_html, panel_before, panel_after, option_content, or link_attrs filter emits tags / attributes outside the switcher's built-in set (which covers nav, button, div, span, a, svg, path with their standard switcher attributes plus lang, dir, aria-*, tabindex, id).

The map follows the standard wp_kses_allowed_html shape: [ 'tag' => [ 'attr' => true, … ], … ].

The default is core’s post allowlist extended with the elements and attributes WordPress core’s own block renderers emit - <iframe> (oEmbeds), inline <svg>, and srcset/sizes on responsive images - so ordinary block content survives escaping. If a page builder or custom block emits markup that still gets stripped, restore it here rather than disabling escaping.

Database string mode only. In files mode (the default) strings are served from the generated files and this filter does not run.

Defaults to vendor/, node_modules/, .git/, tests/, test/, cache/, build/ and dist/.

Patterns are matched relative to the directory being scanned, not against the file’s absolute path. So a vendor/ folder inside the tree you asked to scan is still skipped, while an installation that merely lives below a directory of that name - /var/www/test/, a checkout under build/ - is scanned normally.

Dev-mode guard: a non-array return triggers _doing_it_wrong() and the scanner falls back to the built-in excluded-paths list.

Dev-mode guard: returns that are not array<int,string> trigger _doing_it_wrong() and the provider response is used unfiltered.

PerfLocale bundles no translation memory - this is the single hook point where an integration can answer the lookup itself. Return a non-empty string and it is used verbatim: the provider is never contacted, no provider quota is spent, and the REST response reports "source": "tm" instead of "mt". Two caveats: the string is not passed through wp_kses() the way a provider response is, so return markup you already trust; and the request still counts against PerfLocale’s own hourly budgets (perflocale/mt/rate_limit, perflocale/mt/rate_limit_site) because the rate-limit check runs before the lookup. Return null (the default) to fall through to the provider.

Scope: the block-editor translate endpoints only - perflocale/v1/block-translate on its single-text path (a batch request covering several blocks always goes to the provider, since a multi-leaf walk rarely has every leaf hit) and perflocale/v1/block-translate/from-source, the “fill from source” action. It does not run for whole-post translation, bulk machine-translation jobs, or string translation.

When a default-language post is published, PerfLocale queues a background job that walks every active language and machine-translates the post into it. Before each language it computes a default decision: translate when there is no translation yet, or when the existing translation is an untouched stub (created with empty content). A sibling with non-empty content is assumed to be human-owned and is skipped - republishing the source must never drop raw MT over a translator’s refined text.

Return true to force a re-translation of an already-filled language, or false to skip one. The filter runs after the default language is excluded and after the Auto-Translate Target Languages scope (mt_auto_translate_languages) has been applied, so it only sees languages that were already in play.

Every path that sends a post asks this filter, only for a post that has a password; a post without a password is sent without asking. By default a path sends such a post only when someone picked that post; the automatic runs and the runs over every post do not. $send starts at the path’s default, named by $trigger:

• auto_publish - Auto-Translate on Publish. Default false: the post is not translated.
• auto_create - Auto-Translate on Create (the + Create action). Default false: + Create makes a copy of the original without contacting the provider.
• site_translate - the site-wide job (the Translate the entire site panel and the REST site_wide mode). Default false: the post’s pairs count as skipped.
• bulk - the bulk action on posts selected on the Translations screen, inline or as a background job. Default true.
• cli_ids - wp perflocale translate <id> and wp perflocale translate --post-ids. Default true.
• cli_all - wp perflocale translate --all, in the WP-CLI process or, with --async, as a background job. Default false: the post counts as skipped.
• rest - POST /machine-translate, POST /machine-translate/object and POST /translations/bulk-translate with post_ids. Default true.
• ability - the perflocale/translate-post ability. Default true.
• editor - the block editor’s Fill in from source and the block toolbar’s Translate action on the post being edited. Default true.

A path that is refused skips the post and reports it as it reports any skipped item: bulk runs, the site-wide job and wp perflocale translate --post-ids or --all count it as skipped; wp perflocale translate <id> prints a warning; the REST routes and the editor answer 403 password_protected, and the ability returns a password_protected error, with the message “This post is password-protected and was not sent for machine translation.”

Use it to raise the timeout for bulk jobs, inject proxy/tracing headers, set a custom user-agent, or route calls through a corporate gateway.

The default SSRF validation runs before this filter and cannot be bypassed: the URL is verified against the internal/private-IP blocklist first, then the filter gets to tweak args.

It has two uses:

• Reaching a provider on an internal network. A provider URL whose host is, or resolves to, a private, shared or reserved address is refused, and the refusal message names this filter. To use a self-hosted LibreTranslate on your LAN, or on a Tailscale or carrier-grade NAT address (the shared range 100.64.0.0/10), add the host name or IP address of its URL here.
• Skipping the DNS step for a public provider. A custom provider host (for example a custom AI translator add-on calling api.cohere.ai) listed here skips the slow gethostbyname() lookup, which has no timeout.

Important: a listed host bypasses every check that follows the filter - treat the list as a security-relevant setting. A host you add here returns from validate_url() immediately, so the IPv4 private, shared and reserved range checks, the IPv6 unique-local (fc00::/7) and link-local (fe80::/10) checks, the DNS resolution, and the checks on the resolved address are all skipped for it, whether you add a host name or an IP address. Only the hard-coded localhost list (localhost, 127.0.0.1, 0.0.0.0, ::1, [::1]) is checked before the filter and therefore still applies. Add only hosts you control. Entries are normalised (non-strings dropped, then lowercased); the return value is cast with (array), so returning a non-array does not restore the built-in list - a string becomes a one-element trusted list, and null leaves no trusted hosts at all, sending every request (including the five bundled providers) through the DNS step.

Default trusted hosts (built into PerfLocale) are exactly four endpoints: translation.googleapis.com, api.deepl.com, api-free.deepl.com, api.cognitive.microsofttranslator.com. LibreTranslate, hosted or self-hosted, is not trusted by default. Anything else - a self-hosted LibreTranslate, a custom agency endpoint, an AI gateway - goes through the DNS step and the address checks unless you add it here.

Default 300 - matches what real providers advise during sustained overload, while stopping a malicious or buggy provider returning Retry-After: 86400 from blocking a PHP worker for ~24h per retry. On a 429 the worker first takes max( Retry-After, exponential-backoff ), then caps that at this value, so the effective sleep is min( max( retry_after, 2^attempt ), this_cap ). The cap itself is floored at 1s.

Lets you mask placeholders, strip shortcodes, or pre-substitute branded terms.

The fifth argument is the provider id so a single callback can branch by provider.

PerfLocale does not ship a built-in async callback receiver; this filter is the supported extension point for addons that want to add one. The default return is null, which makes the provider throw RuntimeException instead of saving the untranslated source text into the translation.

Return a non-empty string to use as the translation. Return null (or empty string) to fall through to the throw - appropriate when the addon hasn't received the agency callback yet.

When this fires: the agency returned a 2xx response but the decoded body has no translation string key. PerfLocale then throws, rather than returning the source text as a translation, unless this filter supplies a string. See Machine Translation → External Translation Agency.

Register only leaf text values a human translator would rewrite - plain text, textarea, and rich-text fields. Never structural keys (repeater counts, layout arrays), URLs/emails, serialized arrays, or SEO focus keywords; those belong on perflocale/translatable_meta_keys (the copy/seed list), not here. SEO addons register titles/descriptions here when the "Translate SEO meta" setting is on; ACF/MetaBox/Pods register text fields when "Translate custom fields" is on.

After the filter, PerfLocale drops two kinds of key: any key matching perflocale/translation/dangerous_meta_patterns (never sent to a provider or overwritten), and any mirror key from perflocale/sync/mirror_meta_keys. The fourth argument names the translation the values will be written to, so a callback can compare the two posts. The bundled ACF addon uses it to leave out repeater and flexible-content rows whose structure on the translation no longer matches the source; those keys are counted as skipped.

Return 'text' for plain-text meta (SEO title/description, plain custom fields) so the provider is called in text mode and the result is not entity-escaped; return 'html' (the default) for markup-bearing meta. Unknown keys stay 'html'. PerfLocale groups a post’s translatable meta by resolved format and makes one provider round-trip per format, so declaring a key as text keeps literal characters like & intact instead of turning them into &. The bundled SEO and ACF/MetaBox/Pods addons use this hook to route plain-text fields to text mode. The fourth argument is the source post, so the format can depend on the post’s own data; the ACF addon uses it to route each row of that post by the row’s own field type, so a field name that is plain text in one flexible-content layout and rich text in another is handled row by row.

Rows identical to the source’s are left alone rather than rewritten. Which keys this set governs is narrower than it looks. Seed-only semantics - copied once into a sibling that has none, then owned by that sibling and never overwritten or deleted - are computed from the add-on-contributed keys (perflocale/translatable_meta_keys) plus anything perflocale/sync_fields/for_post appends, minus this set. Seeds are copied only from the group’s default-language post: a value first typed on a translation stays on that translation. A seed-only key whose name matches perflocale/translation/dangerous_meta_patterns is not synced at all, and a key listed in the translation’s _perflocale_seed_cleared meta (the Meta Box addon writes it when a field that held a value is saved empty there) stays empty. The configured Sync fields list and anything added through perflocale/sync_fields mirror unconditionally and cannot be made seed-only from here, so never put a value carrying translatable text into either of those. Mirror keys are also excluded from machine translation.

⚠️ Never put a value that contains translatable text on this list. The mirror is bidirectional: any group member’s save propagates to all the others, so a key holding words is destroyed in both directions - the translator saves and overwrites the original, then the next original save overwrites the translation. Page-builder layout documents hold their text inside them, so the bundled page-builder add-ons treat them (_elementor_data, _fl_builder_data, Oxygen’s _ct_builder_json and its older ct_builder_json spelling, _bricks_page_content, Oxygen 6’s data) as seed-only, and mirror only text-free keys such as Beaver’s _fl_builder_enabled.

Use mirror for values that are genuinely source-owned and carry no words: a flag, an ID, a numeric setting. If you want a structural change to propagate and translated text to survive, you need a format-aware merge that can tell a layout node from a localisable value - a whole-document mirror cannot give you both.

It runs only when a seed is written: the default-language post is saved, the sibling has no rows for the key and has not emptied it on purpose, and the source holds a value. Each row of a multi-value key is filtered on its own. The value arrives unslashed; return the row to write, and PerfLocale slashes it. The bundled Meta Box add-on uses this filter to take a group’s password sub-fields out of the seeded rows, as it does when a translation is created.

Every other registered shortcode's tags are held back from machine translation and restored in the translation unchanged.

Useful for tests, custom in-house AI gateways, or as a forward-compatibility shim if WordPress core renames the underlying function.

Keep the rules about placeholder preservation (the integrity gate enforces them) and the "output only the translation" instruction.

The default is [ 'capability' => 'text-generation', 'temperature' => 0.2, 'timeout' => 10 or 60, 'model' => [ small models ] ]. Recognised keys:

• model - a model ID ('gpt-5.4-mini') or an ordered list of preferences, each a model ID or a [ provider_id, model_id ] pair. It is passed to WordPress’s model preference: the first one a connected provider offers is used, otherwise WordPress chooses. The default is an ordered list of small models (OpenAI mini, Anthropic Haiku, Google Flash). null or [] leaves the choice to WordPress. Entries of any other shape are dropped.
• provider - a provider ID, to use only that provider.
• temperature - default 0.2; null sends none. While a temperature is sent, a model that does not advertise temperature support is not chosen, so an explicit model of that kind needs 'temperature' => null too. When a model refuses the temperature, the call is repeated once without it.
• max_tokens, system_instruction.
• timeout - seconds for the provider request: 10 for editor calls ($fast_fail true), 60 otherwise.

Defaults to 'text-generation'. Set to 'translation' or another capability tag if your AI gateway routes calls by capability.

The default is core/site-title:after. Return a [ block_type, position ] pair, or false to keep the default.

Defaults to dropdown display + compact 16-px flag for header context. Return an empty array to fall back to the global Settings → Language Switcher values.

By default the shim ships on post.php, post-new.php, and site-editor.php - sites running a custom block-editor surface can opt that hook in here.

Use this to remove specific abilities from JS-side registration (e.g. keep translate-post server-only) or to inject custom ability descriptors. The shape is [ 'abilities' => [ { name, label, ... }, ... ] ].

Default requires a logged-in user. Only consulted when the Abilities API integration is enabled.

It receives a slug (deepl, google-cloud-translation, microsoft-translator, libretranslate) and returns the key, or null or an empty string when it has none. Current WordPress releases do not hand these keys out, so the built-in lookup finds none of them: return a resolver when your site keeps them in its own store. Also useful for tests.

PerfLocale ships no GeoIP or exchange-rate provider of its own, so any key those surfaces need is one your site registered - add it here to have your resolver supply it too. Unknown connector slugs simply return null from the resolver and fall through to env / constant / DB as usual.

On language-scoped archive queries PerfLocale replaces WordPress core’s SQL_CALC_FOUND_ROWS full-scan with no_found_rows plus a generation-cached COUNT, reproducing WP_Query::set_found_posts() branch-for-branch so pagination totals stay correct. Return false to keep core’s SQL_CALC_FOUND_ROWS behaviour. It only evaluates for a non-singular main archive query that is not a search, has not already opted out of counting and carries PerfLocale’s language JOIN - all / empty fields, a non-zero perflocale_language_id, on a site that has translation groups.

Use it for content a plugin resolves by IDENTITY - a hash, a slug, a name, a meta value - rather than browsing by language. Scoping such a lookup does not filter it, it breaks it: the lookup returns nothing and the host has no “not found” story beyond an error string or a blank region. The default set is wp_template, wp_template_part, wp_global_styles and wp_navigation; the bundled Contact Form 7, Oxygen and WPForms addons add their own types. Do NOT add a type that is genuinely browsed by language (post, page, product) - that would put every language’s content into every archive, search result and listing.

Off by default because it costs an extra lookup on a hot rendering path; turn it on if you switch themes between requests (a staging/preview setup, or a theme switcher) and would rather pay the lookup than risk serving a part from the previous theme.

Return false to keep template translations entirely manual.

The filter is only reached after PerfLocale has already decided the save is a real one: revisions, autosaves and the auto-draft, trash and inherit statuses never get here, Full Site Editing must be on with the type translatable, and the saved post must itself be the default-language member of its group. Languages that already have a live translation are skipped, so a callback returning true only ever creates what is missing. Each copy is created as a draft seeded with the source’s blocks, so nothing reaches visitors until you publish it.

Dev-mode guard: a return whose shape is not array<string, AddonInterface> triggers _doing_it_wrong() and the registry falls back to the unfiltered addon list.

Lets a single addon opt out of (or into) data deletion regardless of the plugin-wide preference. Receives the planned PurgePlan so callers can branch on which tables / option keys would be removed.

Use it to run an integration in some contexts only, for example not in WP-CLI or not on one site of a network. It is asked once per addon per request, when the registry boots addons (init priority 0 on a normal request), after the quarantine check and before the addon’s own compatibility check.

At that point only request-level context is known: admin or front end, REST (Helper::is_rest_request()), WP-CLI, cron, AJAX and the current site. The language and the queried object are not known yet, so a callback cannot depend on them.

false skips the boot for this request only. The addon’s hooks are not added, perflocale()->is_addon_active() returns false, and the Addons page shows the card as Not running when the admin request itself turned it off. This is not a failure: the addon is not reported as incompatible or quarantined, its failure counter is not changed, and the disabled list behind the Addons page switch stays as it is. true boots an addon that the disabled list turns off. Quarantined addons are skipped before this filter runs.

Theme addons. The Blocksy, Kadence and Neve addons are decided earlier, while the PerfLocale plugin file loads, so that they can register before the theme sets up. For those three, only a callback added by a must-use plugin, or by a plugin that loads before PerfLocale, takes effect. A callback in a theme’s functions.php runs too late for them.

The default of 3 tolerates transient issues like a missing dependency during an upgrade window or a one-off OOM; raise it for flaky network-dependent addons, lower it to fail-fast in development.

The result is memoised per request so the filter only fires once even when many addons boot. Returning 0 (or a negative number) disables quarantine entirely; 1 quarantines on the first failure. Operators see quarantined addons in the Addons admin page with the last error message inline, and can reset via wp perflocale addon reset-quarantine <id>.

The notice is purely a DX hint - soft-prefix per-addon isolation is not enforced (see Hard vs soft prefixes), and the global perflocale_ prefix is the only namespace requirement. The notice is also WP_DEBUG-gated by core, so production users never see it. Filter it off for addons that intentionally coordinate across the addon namespace (e.g. a manager addon cleaning up after a family of related sibling addons).

Each entry is keyed <kind>:<name> and has every key of a core entry: kind (option, network_option, transient, site_transient, post_meta, term_meta, user_meta, order_meta or cron), name, owner (addon:<id>, pro or ext:<slug>), class, export, not_exported, import, uninstall (data or keep; always keep for cron), scope, copy, sync, deactivate, fixture and since. Entries are only added: one that collides with or overlaps a PerfLocale entry, or fails validation, is ignored.

• An exported entry (only into the Add-on data section) must declare sanitize_import, a callable fn( mixed $value, string $name ): mixed the importer passes each imported value through before storing it. An exporting entry without one is ignored, and so is one whose name is a WordPress core option or meta key, or looks like a credential (see perflocale/data_registry/is_secret).
• By default every add-on's exported data is chosen with the one Add-on data checkbox. An exported entry may declare group ([ 'id' => 'my-addon', 'label' => __( 'My add-on', 'my-addon' ) ]) to get its own checkbox with that label; the id is 1 to 40 lowercase letters, digits, - or _.
• sync => 'never' for a key outside the _perflocale_ namespace is enforced when Settings are saved; to keep it out of a sync started another way, also remove it in perflocale/sync_fields.

An extension entry exported into Add-on data whose name looks like a credential (the names the export redaction strips: _api_key, _secret, _password, _token, a name ending in _key and similar) is refused, so its value never travels in an export file. Return false only for a name that holds no secret, such as a _token_count counter; the entry is then exported and imported like any other.

PerfLocale ships the scheduled multi-currency sync mechanism but no rate provider and no endpoint - the built-in provider list is empty, so this filter (or exchange_rates_fetched) is how a site supplies rates. Until one of them is wired, the sync contacts nothing.

The simplest way to supply rates without registering a full provider: return the map you want stored. Also useful for applying a markup or overriding a single currency.

Defaults to the Sync Inventory Across Language Variants setting (wc_sync_stock, default on). Returning false suppresses every sibling write - product fields, variation fields, order-driven stock changes, and CSV-import syncs alike - without touching the stored setting, which makes it the right hook for a temporary freeze during a bulk operation.

This is the site-wide switch; use skip_inventory_sync to exempt a single product instead.

Siblings are located by anchoring on the linked parent product and matching children on their exact normalised attribute set - a variation whose attributes a translator has diverged is skipped rather than guessed at.

Default list: _stock, _stock_status, _manage_stock, _backorders, _price, _regular_price, _sale_price, _sale_price_dates_from, _sale_price_dates_to, _sku, _global_unique_id, _weight, _length, _width, _height, _virtual, _downloadable. The five price keys are removed before the filter runs when Synchronize Prices Across Languages (wc_sync_prices) is off, so a per-language pricing setup already sees the shorter list. Returning an empty array skips the sibling sync for that variation entirely.

Default true. A row with no translations costs one cached group lookup and short-circuits, but importing a fully translated catalogue runs a sibling sync per row - return false to skip it for the duration of the import and do a single resync afterwards instead.

Hooked to woocommerce_product_import_inserted_product_object, so it covers both products and variations written by the importer. Ordinary admin, REST, and quick/bulk-edit saves are unaffected.

With Inventory Sync on, the language copies of a product share one stock, so the cart, add-to-cart, checkout and pay-for-order checks always count the holds of every copy (see Shared stock before payment). The quantity limit shown in Store API product data - product blocks and the Store API products route - is WooCommerce’s own by default and costs no extra query. Return true to count every copy there too, so the limit a shopper sees matches the one the cart enforces. That adds database reads for each translated, stock-managed product on those renders when no persistent object cache is in use.

Asked each time the Store API computes a product’s quantity limit outside a cart.

With Inventory Sync on, the language copies of a product share one stock, so each stock check of a variation in a cart or an order first finds the matching variation of each language copy. PerfLocale stores that answer per variation for up to a day and checks it against the products on every read. Stock quantities, held stock, stock management and the per-product opt-out are always read live and never stored.

Return false to look the matching variations up on every check instead, for example to rule the stored maps out while you look into a stock question. Each cart, checkout and Store API cart request with a stock-managed variation then makes a few more database or object-cache reads. When you return true again, maps stored before you switched them off are used again unless a change made through WordPress, or Clear cache, retired them meanwhile.

After changing translation links of attribute terms directly in the database, outside WordPress, use Clear cache: PerfLocale’s other caches need it too, and it retires every stored map whether or not this filter is set.

This filter does not switch Inventory Sync; use perflocale/woocommerce/inventory_sync_enabled for that.

Default 60. Floor-clamped to 60, so a filter cannot remove the wait. Raise it when database reads can lag the primary or an import keeps a transaction open longer. A very large value stops new maps from being stored; to switch them off, use perflocale/woocommerce/stock_map_enabled.

Off by default. Turn it on only when your page or edge cache honours Vary; otherwise bypass that path in the cache, or add the perflocale_lang cookie to its cache key (see Store API responses and caches).

Asked when a Store API response is served on a request whose URL carries no language. Responses that already carry Cache-Control: no-store, such as the cart and checkout routes, are skipped. The header is added next to any existing Vary value, so WooCommerce’s Vary: Origin stays.

Default is WooCommerce’s own answer, WC_Email::is_customer_email() (and true for an email object with no such method): an email addressed to the customer uses the customer’s language, one addressed to the store admin uses the shop language. Of the nine order emails PerfLocale hooks, new_order, cancelled_order and failed_order go to the store admin.

Returning false does two things: no locale is switched for the body, and the subject, heading and additional content are left as WooCommerce formatted them - the String Translation lookup is skipped too.

By default a translated form owns its whole mail array, ROUTING INCLUDED - the recipient, sender and additional headers were copied when the translation was created and are never re-synced. That is deliberate, because a different recipient per language is a legitimate setup, and editing the source flips the translation to Needs update so the change is visible. Use this filter when you would rather have mail routing follow the source while the wording stays translated.

Gravity Forms keeps forms in its own tables - a GF form id is not a wp_posts id - so per-form translations live in a per-form option (perflocale_gf_translations_{form_id}) keyed by language slug rather than in the post-based translation flow. Return an empty array to leave a form untranslated, or supply the translations array to override labels, descriptions, placeholders, choices, and confirmations programmatically without writing to the option store.

Receives the cleaned, sanitised order array - useful for forcing geo first for staff cookie holders, or falling back to browser while a third-party geo provider is rate-limited.

PerfLocale ships the redirect logic but no provider and no endpoint - the built-in provider list is empty, so the feature contacts nothing until a site wires a source through this filter or through perflocale/geo/lookup_country (the cheaper option when your host already hands you a country header).

Return false to skip GeoIP redirection entirely for the current request - no provider call is issued. Complements the existing perflocale/privacy/consent_given gate.

Default 302 (temporary). Return 301 for permanent SEO consolidation. Allowed values: {301, 302, 307, 308}; anything else silently reverts to the default.

The filter also runs when a visitor opens a post under another language’s slug and the post has a published translation in the current language. There $from_slug and $to_slug are both the current language, and the default is 301: the visitor goes to the translation in one permanent redirect.

Skipping it means those pages carry no Set-Cookie, so a full-page cache in front of the site can store them. Return false to write the cookie in that case too.

Nothing the plugin does depends on that cookie being present for a default-language visitor: the cart, checkout and order emails all fall back to the default language, which is the same answer the cookie would have given. Override this only if something of your own - an edge rule, an analytics script, a CDN cache key - reads perflocale_lang on default-language pages and needs it there.

Translated pages always write the cookie: the WooCommerce Store API posts to an address with no language in it and resolves the shopper’s language from this cookie, so a non-default shopper must carry one.

Use it for decisions the Cookieless mode setting cannot make, such as following one preference category of a consent plugin. It is asked only right before the cookie would be written, so a request that writes nothing never reaches it: a bot, perflocale/privacy/consent_given returning false, headers already sent, an unknown slug, a visitor who already holds this value, no feature that reads the cookie, or a skipped redundant write. It cannot force a write in any of those cases, and its answer does not change whether a visitor is redirected.

The filter wins over the Cookieless-mode setting in both directions: true writes the cookie even in Cookieless mode, and false blocks it while the setting allows it.

In Cookieless mode, hooking this filter also keeps the automatic first-visit redirects (browser language, GeoIP, edge hint) running. With Cookieless mode on and nothing hooked here, the cookie can never be written, so those redirects do not run: without the cookie nothing marks a visitor as returning, and every default-language page would redirect them again.

Return false to suppress the cookie and both redirects until the visitor has granted consent. Default true - the cookie and both redirects run immediately. (To drop the cookie unconditionally without a consent plugin, use the Cookieless-mode setting instead.)

Use it to carry feature flags, per-language A/B variants, fallback chains, or any routing metadata the edge needs without an extra origin round-trip.

The result is stored in the 3-layer cache and contributes to the ETag. Keep additions deterministic (no timestamps, no request-specific data). If the custom fields change at runtime, call \PerfLocale\Api\ConfigController::invalidate() or update any option/setting that already triggers perflocale/settings/updated.

Default true - the payload is a strict subset of what is already rendered to visitors (switcher, hreflang tags, URL structure), so there is nothing private to protect. Return false to require the read capability (any logged-in user) instead. Write endpoints are unaffected - they always require perflocale_manage_languages.

Default true - public-read, because the payload is a strict subset of what is already rendered to visitors (URL mode, default slug, active languages, edge-hint header / cookie names). Return false or a WP_Error to require authentication; return true to keep public-read. Symmetric with perflocale/api/languages_public for the /languages endpoint - write endpoints are unaffected and always require perflocale_manage_languages.

If the filter returns anything other than bool / WP_Error, PerfLocale emits a _doing_it_wrong() notice (dev-mode) and falls back to the default public-read behaviour rather than crashing the endpoint.

While anything hooks this filter, and for any logged-in caller, the endpoint answers with Cache-Control: private, no-store instead of the public cache headers, so a shared cache never stores a response the gate might refuse to another client.

Default true when 2+ languages are active. Return false to show every term across every language in the metabox (e.g. for a custom integration that re-scopes terms in JS).