PHPackages                             blackstone/laravel-model-translations-sync - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility &amp; Helpers](/categories/utility)
4. /
5. blackstone/laravel-model-translations-sync

ActiveLibrary[Utility &amp; Helpers](/categories/utility)

blackstone/laravel-model-translations-sync
==========================================

Synchronize Laravel model translations between models, language\_lines, files and external translation flows.

0.0.4(1w ago)04↓100%MITPHPPHP ^8.2|^8.3|^8.4

Since Mar 11Pushed 1w agoCompare

[ Source](https://github.com/blackstone/laravel-model-translations-sync)[ Packagist](https://packagist.org/packages/blackstone/laravel-model-translations-sync)[ RSS](/packages/blackstone-laravel-model-translations-sync/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (8)Versions (5)Used By (0)

blackstone/laravel-model-translations-sync
==========================================

[](#blackstonelaravel-model-translations-sync)

Laravel package for synchronizing translations between:

- translatable Eloquent model JSON attributes via `spatie/laravel-translatable`
- `language_lines` via `spatie/laravel-translation-loader`
- local Laravel `lang` files
- external translation services such as Crowdin, Lokalise or custom project commands

Pipeline target:

`Models -> DB (language_lines) -> external service -> DB -> Models -> Files`

Requirements
------------

[](#requirements)

- PHP 8.3, 8.4+
- Laravel 11 or 12
- `spatie/laravel-translatable`
- `spatie/laravel-translation-loader`

Installation
------------

[](#installation)

```
composer require blackstone/laravel-model-translations-sync
```

Publish config:

```
php artisan vendor:publish --tag=model-translations-config
```

Model setup
-----------

[](#model-setup)

Add `HasTranslations` from Spatie and the package trait:

```
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;
use BlackstonePro\ModelTranslationsSync\Traits\ModelTranslatable;

class Product extends Model
{
    use HasTranslations;
    use ModelTranslatable;

    protected $fillable = ['title', 'description'];

    public array $translatable = ['title', 'description'];
}
```

Default behavior:

- `getModelTranslationNamespace()` returns snake\_case model basename
- `getTranslatableAttributesForSync()` returns `$this->translatable`

You can override both methods in the model if needed.

Storage format in `language_lines`
----------------------------------

[](#storage-format-in-language_lines)

Model translations are stored as:

- `group = models.{namespace}`
- `key = {id}.{attribute}`
- `text = {"en":"...", "fr":"..."}`

Example:

```
group = models.product
key = 12.title
text = {"en":"iPhone","fr":"iPhone"}

```

Configuration
-------------

[](#configuration)

Published config file: [config/model-translations.php](/Users/rarkhipov/www/laravel/laravel-model-translations-sync/config/model-translations.php)

Main options:

- `models.auto_discover`: discover models from configured paths
- `models.paths`: directories for model discovery
- `models.list`: explicit model class list
- `models.namespace_map`: manual namespace to model mapping
- `locales`: supported locales for sync
- `default_locale`: fallback locale
- `ignore_groups`: groups ignored during file export
- `export_path`: destination for generated lang files
- `export.overwrite`, `export.pretty_print`, `export.sort_keys`
- `sync.stop_on_error`: stop or continue when a pipeline step fails
- `sync.pipeline`: ordered list of artisan commands for the sync pipeline

Commands
--------

[](#commands)

Export models to `language_lines`:

```
php artisan translations:export-models {model?} {--fresh} {--chunk=500} {--dry-run}
```

Import model translations from `language_lines`:

```
php artisan translations:import-models {--locale=} {--group=} {--chunk=500} {--dry-run}
```

Export DB translations to local files:

```
php artisan translations:export-files {--dry-run}
```

Import local files back into DB:

```
php artisan translations:import-files {--dry-run}
```

Run the full pipeline:

```
php artisan translations:sync {--dry-run}
```

Pipeline is config-driven. Example:

```
'sync' => [
    'stop_on_error' => true,
    'pipeline' => [
        ['command' => 'translations:export-models', 'enabled' => true],
        ['command' => 'crowdin:upload', 'enabled' => true],
        ['command' => 'crowdin:download', 'enabled' => true],
        ['command' => 'translations:import-models', 'enabled' => true],
        ['command' => 'translations:export-files', 'enabled' => true],
    ],
],
```

`translations:sync` executes enabled commands in order, warns about missing or failing steps, and stops only when `sync.stop_on_error` is `true`.

Generating translatable JSON migrations
---------------------------------------

[](#generating-translatable-json-migrations)

The package can generate a snapshot-based Laravel migration for safely converting existing scalar/text translatable columns into JSON columns without runtime model scanning inside the migration.

```
php artisan translations:make-translatable-migration convert_translatable_fields_to_json --locale=en
```

Available options:

```
php artisan translations:make-translatable-migration
    {name?}
    {--paths=*}
    {--locale=en}
    {--chunk=500}
    {--force}
```

The command:

- discovers models using `Spatie\Translatable\HasTranslations`
- filters only real DB columns
- writes a fixed snapshot of models, tables, primary keys and translatable attributes
- generates a self-contained migration in `database/migrations`

The generated migration:

- creates `__json_tmp` columns in `up()`
- wraps old scalar values as `{"":"value"}`
- renames temp JSON columns back to the original names
- restores values back to `text` columns in `down()` using the chosen locale

Source of truth
---------------

[](#source-of-truth)

- `translations:export-models`: models are source of truth
- `translations:import-models`: `language_lines` is source of truth
- `translations:export-files`: `language_lines` is source of truth
- `translations:import-files`: lang files are source of truth

File formats
------------

[](#file-formats)

Supported export/import targets:

- `resources/lang/{locale}/*.php`
- `resources/lang/{locale}.json`
- `resources/lang/{locale}/models.php`

Model translations in `models.php` are structured as:

```
return [
    'product' => [
        12 => [
            'title' => 'iPhone',
            'description' => 'Smartphone',
        ],
    ],
];
```

Testing
-------

[](#testing)

```
composer test
```

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance98

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

12d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/886b025ab82664cb06603c610067532bfa7b361b299a0af475278af70b94b0b9?d=identicon)[rkzn](/maintainers/rkzn)

---

Top Contributors

[![rkzn](https://avatars.githubusercontent.com/u/804692?v=4)](https://github.com/rkzn "rkzn (7 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/blackstone-laravel-model-translations-sync/health.svg)

```
[![Health](https://phpackages.com/badges/blackstone-laravel-model-translations-sync/health.svg)](https://phpackages.com/packages/blackstone-laravel-model-translations-sync)
```

###  Alternatives

[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
