Tomato Translations Laravel Package

Technical Evaluation

Architecture fit. The package occupies a narrow but legitimate slot in a Laravel codebase: it centralizes translation keys in the database, exposes a Filament/TomatoPHP admin surface for editing PHP/JSON lang files, and wraps a Google Translations API integration for machine-assisted generation. For a TPM, the value is that it separates three concerns that are usually conflated — storage (DB-backed keys), editing (admin UI for non-engineers), and generation (API-backed plus a CLI path-scoped command). That separation is the reason to look at it at all: you can adopt the editor without the auto-translation, or the CLI step without the UI.

The v1.2.6 addition — an Artisan command that translates a selected path rather than the whole application — is the architecturally significant piece. It converts the package from an admin convenience into a pipeline-capable component: translation becomes a scoped, repeatable, scriptable step aligned to how software is actually released (one module/domain per change) rather than a big-bang locale sweep. That property determines whether localization can be sequenced into sprints or must be gated as a standalone project.

Caveat on fit: the package assumes a TomatoPHP/Filament host application. Outside that ecosystem the integration surface (routes, panel registration, shared UI dependencies) becomes bespoke work and the value proposition degrades toward "a lang-file editor with an API key."

Integration feasibility. Mechanically low-friction: Composer install, package discovery, config publish, credentials in .env, optional migrations for the key store, optional Filament panel registration. No new infrastructure. Critically, there is no runtime dependency on the package for serving translations — it writes files the framework already reads, which keeps the blast radius small and the rollback story simple (revert lang/).

The genuine feasibility question is not "can we install it" but "can we trust the write semantics." The v1.2.6 release note describes the capability in one line and points to a single commit. It documents neither the command signature, whether "path" means directory/glob/namespace, merge-vs-overwrite behavior, dry-run support, idempotency on re-run, provider error handling, nor rate-limit/cost controls. Until those are answered by reading source or running a spike, feasibility is provisionally low-to-moderate: install is easy, safe adoption is unproven.

Technical risk. Ranked:

1. Write semantics against human-curated content (high). An auto-translation command that overwrites existing keys is a destructive operation on copy that may have had brand, legal, and translator review. This is the risk that decides the evaluation, and it is the one most likely to be undocumented.
2. Concentration risk (high, non-technical but decision-relevant). Two stars, zero dependents, single-maintainer ecosystem, last release April 2024. No bus factor, no adopter community to inherit bug fixes, no evidence of responsive maintenance. Priced in, that means "acceptable for an internal admin convenience," not "acceptable as a release-blocking dependency."
3. Provider coupling and cost (medium). Google Translate API introduces credential management, per-character cost, quota/rate-limit failures, and data-egress considerations for any string that is not purely product copy. Failure modes are external and non-deterministic — hostile to CI.
4. Determinism / diff noise (medium). Machine output plus DB key ordering can produce unstable diffs, turning review into rubber-stamping, which quietly defeats the human-review gate you were relying on for risk #1.
5. Version/compat drift (low-medium). Laravel/PHP support ranges are unspecified in the material provided; a 2024-era package may lag current Laravel majors.

Key questions to resolve before any go decision:

• Exact command signature: name, required args, options (--locale, --force, --dry-run, --path), exit codes.
• Does it overwrite, merge, or skip existing translations? Is output idempotent on re-run?
• Is there a preview/diff mode, and what artifact does it emit for review?
• What does "selected path" resolve to — directory recursion, glob, or translation namespace? Does it handle nested files and namespaced keys?
• How are Google API credentials, quotas, retries, and failures surfaced to the caller? Does a partial failure leave files half-written?
• Which Laravel/PHP versions and storage formats (PHP arrays, JSON, both) are supported?
• Is there test coverage for the new command, and does CI exercise it?
• What is the DB key store's migration/rollback story, and how does it stay in sync with on-disk files?

Integration Approach

Stack fit. Strong inside the target envelope, weak outside it. Adopt when: Laravel, file-based lang/ translations, a Filament admin panel already present (or planned), non-engineers need to edit copy, and multiple locales change per sprint. Do not adopt as a general localization strategy off that stack — bridging routes, auth, and panel registration typically exceeds the tool's value, and a TMS or a thin custom editor is the better spend.

Migration path. Treat this as additive, not a replacement. Keep lang/ as the source of truth in VCS; let the package be a producer/editor in front of it. Sequence:

1. Pin v1.2.6 on a branch; confirm Composer resolution against the app's Laravel/PHP constraints.
2. Publish config and run migrations to stand up the key store; verify it imports existing lang/ files without loss or reordering.
3. Register the admin surface in a non-production panel; confirm authorization matches your policy model (translation editing is copy-editing authority — decide explicitly who holds it).
4. Enable the Google integration with a dedicated, quota-limited API key and a budget alarm.

Compatibility. The 1.2.5 → 1.2.6 delta is reported as additive with no breaking change or migration step — low upgrade risk. The real compatibility checks are environmental: Laravel major version support, Filament version alignment, PHP version floor, and whether the command depends on a specific translation driver or only on the DB store. Validate in a scratch app matching production's Laravel/PHP pair before touching the real repo.

Sequencing (recommended).

• Spike first, adopt second. One engineer, one sprint, one low-risk locale, one bounded path (a single module or resources/views, not app/).
• Establish the invariant before scripting: "the command never mutates a reviewed string." If the answer is "it overwrites," either find a skip/force semantics that protects curated content or require a mandatory diff/PR gate before any generated output lands.
• Wire into the release runbook only after repeatability and write safety are proven; keep it out of blocking CI until then.
• Timebox the decision. Given the adoption and maintenance signals, set an explicit re-evaluation date rather than letting a pilot become a silent standard.

Ask: approve a timeboxed spike — one engineer, one sprint, one locale, one scoped path — with a go/no-go based on string quality, repeatability, and safety of write behavior.

Operational Impact

Maintenance. Two maintenance surfaces: the package itself (unmaintained-by-default — plan to vendor/fork or pin hard) and the DB key store, which becomes a second source of truth alongside lang/. That duplication is the core operational cost: someone must own the reconciliation rule when the DB and files disagree, and the rollback story is only clean as long as files remain authoritative and in VCS.

Support. No vendor support, no adopter community, negligible adoption. Internal support means the adopting team reads the source. Budget for that explicitly — "free package" is not zero-cost here. Escalation path is "we fork it," which requires someone with Laravel package fluency.

Scaling. Fine at the single-app, few-locale scale this is designed for. It does not scale into translator collaboration, glossary enforcement, translation memory, per-locale QA sign-off, or auditable approval chains — that is TMS territory. Google API cost scales linearly with characters translated; without scoping discipline ("translate everything each run") cost and review burden both grow faster than locale count.

Failure modes.

• Destructive overwrite of reviewed copy (highest severity; mitigate with diff gate and skip-existing semantics).
• Partial writes on provider failure mid-run, leaving files inconsistent.
• Quota/rate-limit exhaustion surfacing as opaque command failures in automation.
• Credential leakage or misuse — a shared API key with no budget cap is an unbounded cost and egress risk.
• Diff noise / non-determinism degrading review into rubber-stamping.
• Key store drift from lang/, producing translations that exist in the UI but never ship, or vice versa.
• Unreviewed machine translation reaching customers, which is a governance failure this tool makes easier to commit.

Ramp-up. Low for engineers already in the Laravel/Filament ecosystem: install, publish, migrate, register panel — hours to a day, with the real time spent in the spike validating write semantics. Non-engineers get the admin UI with minimal training, but need a written policy on what they may edit and what requires review. The organization-level ramp-up is the governance piece: define who holds copy-editing authority, what the review gate is, and how machine-generated strings are labeled as drafts. That work outlasts the tool and should be treated as the actual deliverable of the pilot.