Translation Module Laravel Package

Getting Started

This package is not a standalone translation tool—it's a module for AsgardCMS (a Laravel-based modular CMS) and expects the surrounding Asgard core, admin theme, and companion modules (especially Language/Locales) to already be installed. Before touching the code, confirm which Asgard version you're on; the idavoll/translation-module package targets the Asgard 2.x era (Laravel 5.x), and installation steps differ between that and modern Asgard.

First steps:

1. Check the dependency tree. Read composer.json from https://github.com/Idavoll/Translation. You need to know which Asgard version and Laravel constraint it targets. If it declares laravel/framework at 5.x, do not attempt to drop it into a Laravel 8–11 app.
2. Install via Composer following the README's module conventions:

   composer require idavoll/translation-module
   

3. Register the module. Asgard modules usually expose a service provider (e.g. Modules\Translation\Providers\TranslationServiceProvider) that must be added to config/app.php or picked up by the module loader, plus registration in the modules_statuses.json / module manifest if your Asgard version uses one.
4. Publish and run migrations.

   php artisan vendor:publish --provider="Modules\Translation\Providers\TranslationServiceProvider"
   php artisan module:migrate Translation
   

   This creates the translations table(s) backing the module.
5. Seed locales first. The module manages translation strings, while the actual language list lives in the Language module. Create at least one locale before adding translations, otherwise the admin screens have nothing to attach to.
6. Log into the admin UI at the configured module route (typically /admin/translation or /backend/translation) to see the translation grid.

First use case: managing UI strings for a multi-language marketing site where content editors—not developers—maintain copy. Add a locale, add a translation key like welcome.headline, publish, and confirm trans('welcome.headline') resolves through the DB-backed translator.

Implementation Patterns

The module follows AsgardCMS conventions: repository-backed models, admin CRUD controllers, permission-gated routes, and an event pipeline. Day-to-day work revolves around those seams.

Programmatic reads/writes via the repository. The module's model is typically Modules\Translation\Entities\Translation with a matching TranslationRepository. Prefer injecting the interface over using the model directly—this is the idiom the rest of the CMS expects:

use Modules\Translation\Repositories\TranslationRepository;

public function __construct(TranslationRepository $translations) {
    $this->translations = $translations;
}

$this->translations->create([
    'key'    => 'welcome.headline',
    'locale' => 'en',
    'value'  => 'Hello there',
]);

Rely on the CMS translator, not __() directly. In an Asgard install the framework's translator is swapped/wrapped so that trans() and @lang() hit the database. Your app code should not care where strings come from—call trans('welcome.headline') and let the module serve it. Mixing hard-coded lang/*.php files with DB strings causes confusing override order; pick one source of truth per key.

Bulk import pattern. For migrations from legacy lang/ arrays or CSV exports, loop and upsert in a console command rather than through the admin UI:

foreach ($rows as $row) {
    $this->translations->updateOrCreate(
        ['key' => $row['key'], 'locale' => $row['locale']],
        ['value' => $row['value']]
    );
}

Fire the module's translation-updated events (if any) or flush cache after the batch, not per row.

Admin UI integration. Extend the module's views/tabs only through the documented extension points (menu registration, permission entries). Touching vendor views directly means upgrades overwrite your tweaks. New fields go in a migration + repository method, not in the Blade template.

Caching. DB-backed translations are slow if read per-request, so production should enable the module's cache layer and rely on it. Wire your deployment php artisan cache:clear / config:clear into any release that touches translation data, and if you have a translation-editing workflow, expose a "flush translation cache" action to editors.

Gotchas and Tips

• The package is effectively abandoned. Zero stars, zero dependents, a NOASSERTION license, and an Asgard-era codebase. Treat it as unmaintained legacy. Before adopting, check whether your Asgard install already vendors the same translation functionality under a different name—duplicating it will cause class/migration collisions.
• NOASSERTION license. This is not "open source with a known license"; it means GitHub could not classify the LICENSE file. Read it before commercial use, and if you can't find a grant, assume all rights reserved and get legal sign-off.
• Version lock is the biggest trap. The package was written against Laravel 5.x APIs. Str::randomForUniqueKeys, Illuminate\Foundation\Auth, and transChoice (removed in Laravel 6) are common failure points. Do not force a composer update beyond the declared constraints without a fork.
• Locale dependency. The Translation module is useless without the Language module providing valid locales. If the admin language list is empty, translation creation silently has nothing to bind to—seed a locale first, and check the foreign-key relationship in the migration.
• Cache staleness is the number-one bug report. Editors save a string and don't see it on the site. Almost always the translation cache wasn't flushed. Add an observer or event listener that clears the module's cache on save/delete, and document that step in your editor runbook.
• Fallback ordering. Laravel's fallback_locale in config/app.php interacts with the module's DB lookups. When a key is missing in a locale, confirm which source answers (DB, then lang/ files, then config fallback) so you don't chase ghost strings.
• Migration collisions. Asgard modules ship their own migrations; if you're upgrading from an older Asgard release, migration names can clash with core translations migrations. Check php artisan migrate:status output carefully.
• Route caching. Admin module routes may break under php artisan route:cache if the module registers closures; if the admin UI 404s after a cache warm, that's usually the cause.
• Extension points over forking. If you must modify the module (new field, new bulk action), fork to a maintained repo under your own namespace, tag it, and pin it in composer.json—don't edit vendor/ directly, because the next composer install in CI will overwrite it.
• Consider migrating off. For anything greenfield, use plain lang/ files or spatie/laravel-translation-loader for DB-backed strings. The module's only real value is its admin UI; if you don't need editor-managed translations in the Asgard admin, you don't need the package.