Field translation overview

The plugin reads the ACF translations mode on each field and applies behavior from the default language to other languages. If a field has no mode, the plugin treats it as ignore.

These modes follow Polylang field translation behavior as documented for ACF Pro.

Supported modes are translate, translate_once, copy_once, sync, and ignore. When DeepL machine translation is unavailable, translate and translate_once degrade to copy_once at runtime.

• translate — see translate mode
• translate_once — see translate_once mode
• copy_once — see copy_once mode
• sync — see sync mode
• ignore — see ignore mode

• Propagation runs from the default source by default; sync (and sync-like container propagation) can also run from non-default sources.
• ignore never propagates values to other language stores.
• Some modes overwrite targets on each save, while others only fill empty targets.
• At save time, machine translation runs synchronously for small workloads and queues background jobs when workload thresholds are exceeded.
• During import, translate and translate_once queue machine-translation jobs when DeepL is available. sync, copy_once, and ignore are handled immediately.

Not all machine-translation work runs in the background. PolyFields estimates workload (field count, propagation units, translatable strings, and character count) and compares it against configurable thresholds to decide whether to translate inline during the request or queue jobs through Action Scheduler (with WP-Cron as a fallback).

• Options save: Below thresholds: machine translation runs synchronously during the save request. Above thresholds: translation jobs are queued and run in the background after the source values are saved.
• Import (from first-use assistant): Always queues machine-translation jobs for translate and translate_once fields when DeepL is available. The import batch itself may still finish in one request for small workloads, but individual translation jobs are always deferred.
• Import (WP-CLI, below import thresholds) — Machine translation runs synchronously during the command, without queuing jobs.
• Import (WP-CLI, above import thresholds) — Uses the same queue-based path as first-use assistant import.

Queued jobs skip targets that already have a value. Retry behavior applies only to async jobs. See Workload thresholds for threshold filters and admin presets.

• Use copy_once for media, relationships, and structural data (for example: hero image, linked CTA page, repeater or flexible layout structure).
• Use translate for content that should be manually translated and kept language-specific over time (for example: headings, body text, and marketing copy).
• Use translate_once for content that needs an initial translation but should not be overwritten afterward (for example: teaser text or intro paragraphs refined by editors).
• Use sync sparingly, only for data that should truly be identical across languages (for example: shared IDs, technical flags, and global configuration values).
• Use ignore for fields that are language-specific and should not be copied automatically (for example: localized legal notes, market-specific disclaimers, and regional messaging).