Weave Code
Localization Laravel Package
webx-ui/localization
Webx UI Localization brings localization tools to your Laravel UI. It offers helpers and components for managing translations, switching locales, and keeping multilingual interfaces consistent, so you can ship apps that feel native across languages with less effort.
Languages for a WebX UI site: the list a site is published in, translated Eloquent attributes, and the dictionary the admin panel is drawn from.
Frequently asked questions about Localization
- How do I install webx-ui/localization in a Laravel application?
- Install it with Composer using composer require webx-ui/localization. The package ships a locales table migration, a Locale model, a Locales service facade, a HasTranslations trait, two middleware aliases (webx.locale and webx.panel-locale), and Artisan commands. The API endpoints and admin panel wiring live in webx-ui/module-admin, so plan to install the wider WebX UI cluster rather than this package alone. Until you run the migration, the service answers from config('webx-localization.locales'), so config and middleware can land before the schema.
- Which Laravel and PHP versions does webx-ui/localization support?
- The supported Laravel and PHP range is not documented in the source excerpt, so confirm it with the maintainers before pinning. It is a conventional Laravel locale vertical with no exotic infrastructure such as queues or external services on the critical path. Version pinning and upgrade rehearsals must cover the whole webx-ui cluster because the split ships in lockstep with the monorepo. Also confirm that your MySQL or Postgres version supports the JSON columns used for translated attributes.
- How does the HasTranslations trait store translated Eloquent attributes?
- It stores every locale in a single JSON column as a map such as {"en": "...", "uk": "..."} rather than in a side translation table. Reads and writes stay single-row, which keeps the model layer simple, but per-language uniqueness and indexed filtering move out of the database and into application scopes. Leaving JSON maps for per-locale tables later is a data migration, not a config change, so get product sign-off before the first translated row is written.
- How do I switch the active locale per request, including in the admin panel?
- The package registers two middleware aliases, webx.locale for the public site and webx.panel-locale for the admin panel, which resolve the active locale through the Locales service facade. The dictionary the admin panel is drawn from comes from panel() dictionary generation, which is separate from the list of languages a site is published in. Register the aliases on route groups rather than globally so panel and front-end locales can differ. Keep an eye on dictionary size if you enable many namespaces.
- How do I clear the localization cache after editing translations?
- Run the webx:locales:clear Artisan command whenever lang files or locale records change, or set WEBX_LOCALIZATION_CACHE=false in local development. Cache invalidation rides on webx-ui/cache via CacheGroups::LOCALES, so stale translations are the most probable day-one support ticket. Wire the clear command into your deploy hook instead of relying on a wiki page. If a default locale looks wrong after a manual fix, a cache clear is usually part of the recovery.
- Can webx-ui/localization enforce unique translated slugs per language?
- No. Translated attributes live in a JSON column, so the database cannot enforce a unique index on a translated slug. Slug localization and translated address uniqueness are the scope of webx-ui/routing, which ships a OneSpellingPerAddress route guard. Scope that as a separate workstream or you will promise something this package cannot deliver.
- Can I install webx-ui/localization before the locales table exists?
- Yes. Until the locales table is migrated, the Locales service answers from config('webx-localization.locales'), so installation and configuration do not fail on a missing schema. That makes phased rollouts safer because config, middleware, and route guards can land ahead of the migration. Seed the config list with the locales you intend to publish so behaviour stays consistent before and after the migration.
- How do I filter or order Eloquent models by a translated value?
- Use the translation scopes the package provides: whereTranslation, whereTranslationLike, and orderByTranslation. They operate on the JSON map in application code, so filtering by a translated slug or title is not backed by a per-language index. Check the exact SQL emitted by whereTranslationLike on your MySQL or Postgres version before promising performance on large tables, since it may not be index-assisted.
- What happens if two locales are marked as the default?
- The exactly-one-default rule is enforced by the Locale model on save, not by a database constraint, so concurrent saves or raw SQL can leave two defaults or a denormalised code. Recovery typically requires fixing the rows and clearing the localization cache. Treat it as an operating rule in your runbook, and route all default-locale changes through the model rather than direct queries.
- Is webx-ui/localization maintained, and what should I consider before adopting it?
- It is a read-only split published from the webx-ui/webx-ui monorepo with zero stars, zero dependents, and a single vendor, so the bus factor is one and there is no independent adoption to learn from. Issues and PRs route upstream with no SLA, meaning every upgrade is wait for upstream and re-pin. Frame the decision as adopting WebX UI as a platform rather than this package a la carte, and budget for the three-to-four package cluster including module-admin, routing, and cache. Editing files under vendor/webx-ui/localization is unsupported, so missing seams become upstream requests.
Weaver
How can I help you explore Laravel packages today?