---
title: "Translatable for Laravel — docs | Roundly"
description: "Developer docs for Translatable for Laravel: JSON locale-map attributes, fallback modes, validation, query scopes, translation status and per-locale slugs."
url: https://roundly-consulting.com/open-source/docs/translatable-for-laravel
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

Open source

# Translatable for Laravel

Install

`composer require roundly-consulting/translatable-for-laravel`

Requires: PHP ^8.4 · Laravel ^12.0|^13.0

[GitHub](https://github.com/roundly-consulting/translatable-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/translatable-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly)

## Overview

A native translatable-attributes layer for Eloquent. Each translatable attribute is a plain locale map stored in a single json/jsonb column, and reads resolve the current locale through a configurable fallback chain so content never renders blank. Around it: hardened write paths, a Translatable facade with validation and search helpers for admin forms, translation-status reporting, opt-in change events and per-locale slugs through sluggable-for-laravel. MIT-licensed and built only on Laravel and Roundly’s own packages — zero third-party dependencies.

### What you get

#### One column per attribute

Each translatable attribute is a plain JSON locale map in a single jsonb column — add a locale without a migration.

#### Fallback chain

None, Fallback or Any — reads fall back to the fallback locale, then to any value, so content never renders blank.

#### Hardened write path

Locale keys are validated on every write, values must be scalars, and strict mode rejects unsupported locales.

#### One facade, injectable manager

Locales, fallback resolution, input normalisation, validation rules, partial updates and search on one facade — or inject its manager.

#### Translation status

Missing locales per field, a completeness score for progress bars, a missing-locale scope and a drop-in Blade badge.

#### Per-locale slugs

sluggable-for-laravel builds a slug per locale from the same locale source of truth — two traits, no cast.

#### Opt-in change events

One TranslationsChanged event per save — queue an AI fill of missing locales without overriding the model.

### Documentation

#### [Installation](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/installation.md)

Install via Composer and optionally publish the config and validation language lines — there are no migrations to publish.

#### [Configuration](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/configuration.md)

Every config key, its default and env variable — fallback locale, fallback mode, strict locales and the supported-locale source.

#### [Schema and storage](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/schema.md)

Add jsonb locale-map columns with the translatable() Blueprint macro; values are stored as a plain JSON object with no wrapper.

#### [Translatable models](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/models.md)

Add the HasTranslations trait and the Translatable contract, list attributes in $translatable, and optionally override fallback per model.

#### [The Translatable facade](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/facade.md)

Every locale-map helper on one facade — supported locales, locale checks, fallback resolution, admin input, rules, search and usingLocale().

#### [DI and actions](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/without-facade.md)

Inject TranslationManager instead of calling the facade — the same API as an explicit dependency. There are no action classes: it’s pure computation.

#### [Reading and writing](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/reading-writing.md)

Read the current locale through the fallback chain, target a locale explicitly, and write single values or whole locale maps.

#### [Fallback modes](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/fallback.md)

Choose how far reads fall back — exact locale only, the fallback locale, or any available value — globally or per model.

#### [Input and validation](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/input-validation.md)

Hardened write paths, fromInput() normalisation, single-locale checks, validation rules, full-form and partial-update recipes and concurrent edits.

#### [Serialization](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/serialization.md)

toArray(), toJson(), JSON responses and API Resources emit each attribute’s resolved locale value, not the raw map.

#### [Translation status](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/translation-status.md)

Missing locales per field, whole-model completeness for progress bars, status exclusions and a drop-in Blade status badge.

#### [Querying and search](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/querying.md)

Driver-agnostic per-locale scopes, a missing-locale scope for fill queues, and literal, case-insensitive search across locales.

#### [Events](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/events.md)

Opt in to one TranslationsChanged event per save — queue an AI fill of missing locales or bust caches without overriding the model.

#### [Per-locale slugs](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/slugs.md)

Per-locale slugs via sluggable-for-laravel — two traits, two interfaces, no cast — sharing the same locale source of truth.

#### [Artisan about](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/about-command.md)

The package’s php artisan about section — locale count and source, fallback mode and switches, never your locale list.

#### [Exceptions](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/exceptions.md)

Every package error extends TranslatableException — malformed locale keys, non-scalar values, unloaded columns and non-translatable attributes.

#### [Testing](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/testing.md)

No fake by design — pin locales and fallback via config or a manager swap, assert with plain Pest, run the suite on SQLite, PostgreSQL or MySQL.

#### [Requirements](https://roundly-consulting.com/open-source/docs/translatable-for-laravel/requirements.md)

PHP 8.4+ with ext-json, Laravel 12 or 13, PostgreSQL 12+ or MySQL 8.0.23+; three Roundly packages install automatically.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source.md)