perf(wpml): opt-in guard for ACFML's front-end field-definition translation

[parisek]

Closes #131.

The problem

ACFML translates ACF field definitions — labels, instructions, placeholders, prepend/append, choices, message — on every request that loads a field group. ACFML\Strings\FieldHooks implements IWPML_Frontend_Action, so it registers on the front end with no is_admin() guard and hooks acf/load_field.

Every field then reaches an unmemoized linear scan over a static array, run through WPML's functional library with a closure allocated per element. On a page view none of those strings is rendered, so the whole walk is discarded.

Measured

Site with 117 field groups and 972 top-level fields:

	time
baseline	1.09–1.13 s
group-level translation off	1.04–1.14 s (no change)
field-level translation off	0.29 s

A PHP-FPM slowlog over 3973 slow requests put 71 % of deepest-frame samples inside wpml/fp + wpml/collect. Rendered HTML is byte-identical once per-render uniqueId() values are normalised.

Only the field level is expensive, so the flag switches off both by way of the one filter ACFML provides — the cost lives entirely in the fields.

Off by default, and that is a refusal

Switching it on is wrong for a site that renders field definitions to visitors:

• a theme calling acf_form() — placeholders, instructions and labels become visitor-facing
• a template printing a select/radio/checkbox choice label rather than its value

Neither is detectable from the kit, so the consuming site asserts it. Same rule as ADR-0007: where no static proof exists, refuse.

Rejected: auto-detecting acf_form()

It looks available and it is a trap. acf_form_head() → acf_enqueue_scripts() → ACF_Assets::add_actions(), which guards itself with acf_has_done( 'ACF_Assets::add_actions' ). That function sets the flag it reads — verified in api-helpers.php:

function acf_has_done( $name ) {
	if ( acf_raw_setting( "has_done_{$name}" ) ) { return true; }
	acf_update_setting( "has_done_{$name}", true );
	return false;
}

Calling it from a guard would make ACF's own add_actions() believe it had already run and skip registering its asset actions. The detection would break the exact case it was added to protect.

Four contexts, and naming all four is load-bearing

Admin, AJAX, REST and WP-CLI keep the translation. Gutenberg loads field groups over REST, ACF talks to admin-ajax from inside the editor, and migration scripts run under WP-CLI — none of the three is is_admin().

An is_admin()-only guard therefore shows an editor untranslated labels, which nobody reports as a bug in a performance flag. The test proves the difference: reducing the guard to is_admin() alone fails exactly the AJAX and REST cases and nothing else.

The callback returns the incoming value rather than true, so it stays a veto and cannot overrule another plugin's refusal.

Why this is not #107

#107 was closed unmerged, because a shared workaround would outlive the bug it worked around. Right there, and it does not carry here:

	#107 (acf/load_reference leak)	this
who pays	one caller outside WPML's own plugins	every front-end render
fixed upstream	yes, acfml 3.0-b.1	no
workaround lifetime	would outlive the bug	bug has no end date

Verified rather than assumed: on a site running acfml 3.0-b.1 / sitepress 5.0.0-b.1, the seven files on the hot path are byte-identical to 2.2.4 and the bundled wpml/fp has identical MD5s. The same comparison does pick up 3.0-b.1's one change — the remove_filter hook-name fix from #107 — so it is not a blind diff.

Retiring this is a one-line default flip once ACFML memoizes its lookup.

Notes

The REST test runs in its own process: a constant cannot be undefined, and REST_REQUEST left standing made every later test in the run look like REST — four unrelated failures before it was isolated.

Downstream implementation and the original evidence: portadesign/sloneek#103. This is that filter moved up, with the four contexts unchanged.

[parisek]

Agent review, 2026-08-27 — Codex (gpt-5.3-codex) and Fable, blind to each other

Both reviewed this PR and #93 together. Codex: sound, no correctness defect. Fable's findings were about adoption and shape, and two of them are now fixed.

Fixed

Finding	Reviewer	What changed
The flag exists only in a changelog line and a docblock — README has an ACF section and a Performance section and neither gets a row	Fable	properties-table row + a section next to Performance
The method comment says an unclassified context keeps the translation; the code does the opposite	Codex	corrected — the opposite is the policy
A safe read-only alternative to acf_has_done() exists	Codex	this is the one that changed the design — see below

Codex found the half I got wrong when rejecting auto-detection

The rejection of acf_has_done() stands: it writes the flag it reads, verified again in the installed ACF. But Codex pointed at the getter that function itself calls first — acf_raw_setting() — which reads the same state without touching it.

So acf_form() is detectable safely, and the earlier commit rejected the whole idea on the strength of the wrong half. The guard now steps aside on any front-end request that has set a form up, without being told.

That is what makes the default flip defensible, and the default is now on.

Two shapes, and they were never equal

• acf_form() — detects itself, handled above.
• A template printing a select/radio choice label rather than its value — still undetectable, and still what the property is for. Named in the README as something to check rather than assume when moving a large existing site onto this version.

Measured on the current stack

	min
translation on	479 ms
translation off	370 ms

And the decisive one — kit default on, with the reference site's own functions.php filter removed: 342 ms, against 341 ms with that filter back. The kit's default fully replaces the downstream copy, which is what licenses deleting it.

Rejected

• A Site Health check listing field groups that use select/radio/checkbox (Fable). Presence is not usage — most sites have choice fields and never print a label, so the check would be noise on every site and silence on none.
• Renaming to a positive $acfml_translate_frontend_fields (Fable). It reads better in isolation and worse at the call site: the property would then have to default false to mean the same thing, and "translate = false" is a subtler double negative than "skip = true".

Where a reviewer was wrong, for calibration

Fable's cross-cutting point 2 argued PR #93 should be a StarterBase property like this one, on the grounds that a property "can be flipped once for the whole site" while a parameter needs timber_context() edited. Both need timber_context() edited — the kit does not call formatFields('option') itself; the downstream timber_context() does. The conclusion is still worth acting on for a different reason (a third positional boolean invites a fourth), but the argument given for it does not hold.

Codex could not reach the GitHub API and reviewed from local branches, commit messages and installed plugin sources. Its separate-process REST test and PHPStan run were blocked by a read-only sandbox, not by the code — both pass here.