Translations Laravel Package

Technical Evaluation

Architecture fit

• EscolaLMS/Translations is a modular Laravel package in the EscolaLMS suite (headless LMS composed of small, opt-in Composer packages). It provides database-backed translation management with HTTP API endpoints rather than relying solely on Laravel's file-based lang/ resources.
• Fits a Laravel service architecture using service providers, publishable config/migrations, and package-level routes — the standard shape a TPM can expect to slot in without forking core framework behavior.
• Because it exposes API endpoints and ships OpenAPI annotations (evidenced by the swagger fix in 0.1.1), it is designed to be consumed by a separate admin/frontend client, not just by PHP developers. That is a meaningful product lever: translation editing can be delegated to non-engineers.

Integration feasibility

• Low-to-moderate. Standard install path: composer require escolalms/translations, publish config/migrations, run migrations, seed from existing lang/ files, wire authentication/authorization around the endpoints.
• 0.1.1 is a documentation-surface fix only (swagger generation). It does not change runtime behavior, schema, or public API shape. There is no migration or compatibility action implied by this release itself.
• Real feasibility risk sits in the unverified edges: exact Laravel/PHP version constraints, coexistence with other EscolaLMS packages (core, auth), and the auth model protecting translation write endpoints.

Technical risk

• Pre-1.0 stability: at 0.1.x, SemVer guarantees are effectively absent. Any minor release can break API contracts. Pin exact versions and treat upgrades as change-controlled.
• Low release-notes granularity: "fix swagger" is the entire changelog for 0.1.1. That tells us nothing about upstream CI, test coverage, or whether the fix altered generated route annotations. Assume documentation quality is a leading indicator of project maturity.
• Bus factor: single contributor attributed on this release (@mako321), small community package. Support is best-effort via GitHub issues — no vendor SLA.
• Overlap risk: functionally overlaps Laravel's native localization and alternatives such as spatie/laravel-translation-loader. Adopting this package is a commitment to the EscolaLMS ecosystem, not a neutral utility choice.

Key questions

1. What are the declared composer.json constraints for Laravel and PHP, and do they match our runtime?
2. Is translation data DB-backed only, or does it merge with file-based lang/ fallbacks? What is the fallback chain per locale?
3. How are the write endpoints authorized — does it integrate with escolalms/auth and role-based permissions, or is it open by default?
4. Is there caching (per-request, Redis, tagged invalidation) for the translation lookup path? At what request volume does an uncached DB lookup become a latency problem?
5. Does the 0.1.1 swagger fix mean the OpenAPI spec is now generated correctly and usable as a frontend contract, and is that spec versioned?
6. Is multi-tenancy or per-course/per-package scoping of translations supported?

Integration Approach

Stack fit

• Assumes a Laravel monolith or modular monolith in the EscolaLMS style. If our product is a single Laravel app with a separate SPA/Vue admin, the fit is strong: API-driven translation management is precisely the pain point this addresses.
• If we are not using EscolaLMS elsewhere, adopting this package in isolation imports a dependency on EscolaLMS conventions (auth, user model assumptions) with little upside over spatie/laravel-translation-loader.

Migration path

• Phase 1: install on a scratch branch; publish and inspect migrations; document the resulting schema before anyone writes to it.
• Phase 2: import existing lang/ files via a one-off artisan command or seeder; diff imported keys against source to confirm no loss.
• Phase 3: run file-based and DB-based resolution in parallel behind config, with DB as read-through and files as fallback. This makes rollback a config flip rather than a data restore.
• Phase 4: cut over once key parity is verified across all shipping locales.
• Rollback: keep the lang/ files in the repo until at least one full release cycle has passed post-cutover.

Compatibility

• Pin to 0.1.1 explicitly ("escolalms/translations": "0.1.1") rather than a caret range — pre-1.0 caret ranges resolve to >=0.1.1 <0.2.0, which permits breaking changes in patch-adjacent minors.
• Verify coexistence with any already-installed EscolaLMS packages; shared transitive dependencies are the most likely source of conflict.
• Confirm the package's route prefix and middleware do not collide with existing API routes.

Sequencing

1. Technical spike: install, generate swagger, confirm the 0.1.1 fix actually yields a valid spec (this release's only deliverable).
2. Security review of translation endpoints — this is a gate, not a task.
3. Import tooling and key-parity validation.
4. Parallel-run in staging with cache layer evaluated.
5. Admin UI integration against the generated OpenAPI contract.
6. Production cutover with file fallback retained.

Operational Impact

Maintenance

• Expect a low-but-unpredictable upgrade cadence. Pre-1.0 packages with sparse changelogs require reading diffs, not release notes. Budget a recurring (e.g. quarterly) dependency review rather than reactive patching.
• Every upgrade should be treated as potentially breaking until the diff confirms otherwise — 0.1.1's changelog demonstrates that release notes alone are not a sufficient signal.

Support

• Community-only: GitHub issues, no commercial backing apparent. Internal ownership must be assigned to a named engineer; there is no escalation path.
• Mitigation: keep the integration surface narrow (config + one service wrapper) so that forking or replacing the package remains a days-scale task rather than a rewrite.

Scaling

• Primary scaling concern is the read path: translation lookups on every request. Without caching, this adds a DB round-trip per request and scales linearly with traffic and locale count.
• Validate cache invalidation on translation writes before production — stale translations are a visible, hard-to-diagnose user-facing defect.
• Write path scales fine; translation edits are low-frequency, human-driven.

Failure modes

• Cache invalidation miss: edited translation not appearing; erodes trust in the admin tooling.
• Missing-key regression: a key present in files but dropped during import surfaces as a raw key string in the UI.
• Auth misconfiguration: unprotected write endpoints allow arbitrary content injection — highest-severity risk in this integration.
• Upstream breakage on upgrade: pre-1.0 API change breaks admin frontend contract with no deprecation window.
• Swagger/docs drift: if 0.1.1's fix is not regression-tested upstream, the generated spec can silently fall out of sync with actual routes, misleading frontend consumers.

Ramp-up

• Low for a Laravel-fluent engineer: standard package conventions, familiar migration/seeder patterns. Estimate 1–2 days to productive, excluding auth review.
• Non-trivial for the product side: someone must own the translation workflow (who edits, who approves, which locales ship) — the package supplies mechanics, not governance.
• Documentation is thin; expect to write internal integration notes covering schema, fallback order, and cache behavior as a prerequisite for handoff.