Statamic Magic Translator Laravel Package

Getting Started

This release is a translation/localization addon for multisite Statamic-style content: it walks a source entry's field data and produces a localization in another site, now including Group fields (nested groups and groups arriving via imported fieldsets) and preserving Link field values (URLs and referenced entries).

Minimal steps:

1. Install and publish config: composer require <vendor>/<package> then php artisan vendor:publish --tag=<package>-config. Confirm the addon appears under Addons in the Control Panel.
2. Verify multisite is configured (config/statamic/sites.php) with at least two sites and that the target site's locale is set — translation behavior is driven off site/locale pairs, not off the entry itself.
3. Look first at the package's config file (field-type allow/deny lists, "translatable" toggles) and its service provider bindings. That's where per-field-type behavior is decided.
4. Look second at the tests directory — for v0.4.0 specifically, the Group-field and Link-field test fixtures are the fastest way to understand what "nested" and "opted-out" mean in practice.

First use case: create a simple entry with a single Group field containing two text sub-fields, run the translation into a second site, then re-run it to confirm overwrite behavior is idempotent. Once that's green, add a Link field pointing at another entry and confirm the reference survives.

Implementation Patterns

Field-type-driven translation. The package decides what to do per field type. Group fields are now recursed into rather than treated as opaque blobs; fields imported from fieldsets are resolved through the fieldset reference, so a Group defined in a shared fieldset behaves the same as one defined inline. Design your blueprints assuming Group nesting is supported but that anything non-localizable is deliberately skipped.

Opt-out by field, not by blueprint. Because non-localizable and opted-out children "remain untouched", you can build a single blueprint with a mix of translatable and non-translatable sub-fields and let the package filter. This is the preferred pattern over maintaining parallel blueprints per site — fewer blueprints to keep in sync, and the target localization keeps its own values for the opted-out children.

Overwrite vs. create. The Link-field fix explicitly covers "creating or overwriting a localization". Treat translation as an upsert: you can safely re-run it against an existing localization to refresh content after the source changes. If you need to protect manually edited target content, that protection has to live in your own workflow (e.g. a status flag or a queue job that skips entries in a reviewed state) — the package will overwrite what it's told to translate.

Integration with publish workflows. The natural fit is a queued job or a Statamic action/command fired on entry save, Entry::published events, or a scheduled sync. Wrap translation per-entry and catch failures individually so one bad field doesn't abort a batch. For large sites, chunk by collection rather than iterating all entries.

Link fields need referential awareness. Since Link fields can hold either a URL or an entry reference, ensure translations run after the referenced entries exist in the target site. In a cold-start scenario (translating a whole site for the first time), translate in dependency order, or accept that link references may point to entries that only later get created and re-run the sync afterwards to settle them.

Group fields as content blocks. Nested groups are commonly used as repeatable page-builder blocks. If your set/group structures include assets or other non-localizable types inside the group, expectation-set with your editors: those children will arrive empty in the target site and need manual population. Consider mirroring those asset fields with a shared/synced site configuration instead.

Gotchas and Tips

• Opted-out children are not cleared. "Remain untouched" means an existing target value stays as-is. If you expect a field to be emptied by a translation, it won't be — that's a data-model assumption bug, not a package bug.
• Fieldset indirection bites. Fields imported from fieldsets are resolved by handle; if you rename a field inside a fieldset, previously stored group data may no longer line up with the blueprint and will silently be skipped. Diff fieldset handles when translation output looks incomplete.
• Link-only entries. The v0.4.0 fix targets entries whose only meaningful content is the Link field. If you're on ≤0.3.x and see references dropped when creating localizations, that's the bug — upgrade before debugging your own code.
• Group nesting depth. Deeply nested groups plus conditional field visibility can produce fields that exist in the blueprint but not in the source data. Test with a real entry that has partially-filled groups rather than a fully-populated fixture.
• Debugging silent skips. The package intentionally no-ops on non-localizable fields, so "nothing happened" is ambiguous. Temporarily narrow the config to a single field type and translate a one-field entry to isolate whether the issue is eligibility or the translation itself.
• Extension points. If you need custom handling for a field type the package doesn't know about, look for the field-type resolver/registry binding in the service provider and register your own handler rather than forking — the Group recursion and Link preservation both arrived as versioned changes, and a fork will make those upgrades painful.
• Version pinning. At 0.x, treat minor bumps as potentially behavior-changing: 0.4.0 altered which fields get translated (groups now included). Read the release notes before upgrading in production and re-run a representative translation afterwards to diff the output.
• Prettier/tooling churn in this release is irrelevant to runtime behavior; don't let it distract from the two content-affecting lines when writing your upgrade notes.