Localisation Laravel Package

Getting Started

• This package rarely runs standalone: it is a core-adjacent piece of the Laravel Enso ecosystem. Install it as part of an Enso application, or manually with composer require laravel-enso/localisation and verify it pulls a matching laravel-enso/core version.

• Publish and migrate:

  php artisan vendor:publish --provider="LaravelEnso\Localisation\LocalisationServiceProvider"
  php artisan migrate
  

  If tag-based publishing is available, prefer --tag=localisation-config and --tag=localisation-migrations.

• Populate the languages table. Either create rows through the Enso admin UI / a seeder, or import your existing resources/lang directory:

  php artisan list | grep -i localis   # confirm command names for your version
  php artisan localisation:import
  

• Where to look first:

  • The published config file — default locale, enabled languages, import/export paths.
  • src/App/Language.php — the model, scopes, and helpers (default, status, iso).
  • The package routes/ and Http/Controllers — the API endpoints you will wire a language switcher to.
  • The languages migration — column semantics and defaults.

• First meaningful use case: import en so it becomes a language row, add fr, expose a language-switcher control backed by the package endpoint, and set the application locale from the persisted choice. You now serve the app in two languages.

Implementation Patterns

• Querying available languages — treat the DB rows as the source of truth, not hardcoded arrays:

  $active  = Language::where('status', 1)->orderBy('name')->get();
  $default = Language::where('default', true)->first();
  

• Locale middleware — resolve the locale from session, then the authenticated user's preference, then the default row, then config('app.fallback_locale'):

  public function handle($request, Closure $next)
  {
      $iso = session('locale')
          ?? optional($request->user())->language?->iso
          ?? Language::where('default', true)->value('iso')
          ?? config('app.fallback_locale');
  
      app()->setLocale($iso);
  
      return $next($request);
  }
  

• Language switcher — post the selected iso to the package route (check routes/ for the exact URI), persist it to the session and/or the user profile, and redirect back. Do not hardcode ISO codes in the frontend; hydrate the dropdown from the API and cache it client-side.

• Default-language management — wrap the flip in a transaction and unset the previous default in the same operation. If you build a custom admin screen, put this in a small service or model observer rather than in the controller.

• Import/export round-trip — use import to seed the DB from resources/lang/*, edit translations in the UI, then export to write them back to PHP files so the changes land in version control. Keep the DB authoritative during development and export deliberately.

• Integration with Enso builders — the model is ordinary Eloquent, so Language can be dropped into Enso Form/Table builders if you are building a custom management screen; otherwise the package's own endpoints are sufficient.

• Vendor translations — sync only application-level keys. Leave resources/lang/vendor/* alone; the export/import tooling is not designed to round-trip third-party translation packs.

Gotchas and Tips

• Compatibility is the biggest risk. Last release November 2020; Laravel 9+/PHP 8.1 may require a fork. Check the package composer.json constraints against your Enso core version before adopting, and pin both together.
• Small package, small bus factor. With ~13 stars the surface is stable but maintenance is tied to Enso releases; budget for reading the source rather than relying on documentation.
• Migrations collide. The package creates the languages table. If another package or a previous project already defines it, skip or rename the published migration rather than editing it in place.
• Single default must be enforced in code. A boolean default column has no natural uniqueness constraint; enforce the invariant in a transaction and never let two rows be default.
• Session vs. user preference conflicts. Pick one source of truth in the middleware. A classic bug: a user changes their profile language in one tab while the stale session locale keeps winning.
• Config and route caching. config:cache and route:cache hide newly published config and provider changes. Re-run php artisan optimize:clear after adding locales or republishing.
• Per-request queries. The language list is small but queried on every request through the middleware; memoize it or load it once at boot rather than hitting the DB repeatedly.
• Export overwrites files. Run exports on a clean git tree and review the diff — output can reorder arrays or drop comments.
• Locale code drift. en, pt_BR vs pt-BR, and resources/lang directory names must match config/app.php and the DB iso values exactly. Mismatches fail silently as fallback keys.
• Missing translations. If import leaves the default language incomplete, you will see raw keys rather than text; verify the default row's files exist and the fallback locale is configured.
• Middleware ordering. The locale middleware must sit after StartSession and, when using user preferences, after Auth.
• Debugging a no-op switcher. Check in order: middleware registered, session driver writing, the row's status flag, and whether locale was cached at bootstrap.