spatie/laravel-translatable 是面向 Laravel 的多语言模型扩展包。它的核心设计是把翻译直接以 JSON 形式存储在模型自身的列上,不需要额外的翻译表,也不需要中间表(pivot)。
一、用途 用于让 Eloquent 模型的某些属性支持多语言。当查询涉及可翻译模型、翻译、多语言属性等场景时适用。
二、主要能力
- 声明可翻译属性:推荐使用 PHP 属性 #[Translatable] 并引入 HasTranslations trait。
use Illuminate\Database\Eloquent\Model; use Spatie\Translatable\Attributes\Translatable; use Spatie\Translatable\HasTranslations;
#[Translatable('name', 'description')] class NewsItem extends Model { use HasTranslations; }
该属性接受可变数量的列名。也支持 $translatable 属性写法:
class NewsItem extends Model { use HasTranslations;
public $translatable = ['name', 'description'];
}
两者同时存在时,其值会被合并并去重。
- 迁移:可翻译列必须是 json 类型(若数据库不支持 json,则用 text)。每个可翻译属性对应一列,该列以 JSON 对象保存所有语言。
Schema::create('news_items', function (Blueprint $table) { $table->id(); $table->json('name')->nullable(); $table->json('description')->nullable(); $table->timestamps(); });
- 设置翻译:
// 当前语言(通过 app()->getLocale()) $newsItem->name = 'Hello';
// 指定语言 $newsItem->setTranslation('name', 'en', 'Hello'); $newsItem->setTranslation('name', 'nl', 'Hallo');
// 一次设置多个语言 $newsItem->setTranslations('name', ['en' => 'Hello', 'nl' => 'Hallo']);
// 使用按语言组织的数组进行批量赋值 NewsItem::create([ 'name' => ['en' => 'Hello', 'nl' => 'Hallo'], ]);
$newsItem->save();
- 获取翻译:
// 当前语言 $newsItem->name;
// 指定语言(默认回退到配置的回退语言) $newsItem->getTranslation('name', 'nl');
// 不使用回退 $newsItem->getTranslationWithoutFallback('name', 'nl');
// 某个属性的全部翻译 $newsItem->getTranslations('name'); // ['en' => 'Hello', 'nl' => 'Hallo']
// 所有可翻译属性的全部翻译 $newsItem->translations;
// 该模型拥有翻译的所有语言 $newsItem->locales();
- 按语言查询:
// 拥有指定语言翻译的模型 NewsItem::query()->whereLocale('name', 'en')->get();
// 在任一指定语言中有翻译的模型 NewsItem::query()->whereLocales('name', ['en', 'nl'])->get();
// 按翻译值过滤 NewsItem::query()->whereJsonContainsLocale('name', 'en', 'Hello')->get();
- 删除翻译:
$newsItem->forgetTranslation('name', 'nl'); // 某个属性的某个语言 $newsItem->forgetTranslations('name'); // 某个属性的所有语言 $newsItem->forgetAllTranslations('nl'); // 所有可翻译属性中的某个语言
- 回退行为:默认情况下,当翻译缺失时 getTranslation() 会回退到 config('app.fallback_locale')。可按模型覆盖:
class NewsItem extends Model { use HasTranslations;
public $useFallbackLocale = false; // 为该模型禁用回退
public function getFallbackLocale(): ?string
{
return 'en'; // 自定义回退语言
}
}
- 测试示例:
use Spatie\Translatable\Facades\Translatable;
it('stores a translation', function () { $newsItem = NewsItem::create(['name' => ['en' => 'Hello']]);
expect($newsItem->getTranslation('name', 'en'))->toBe('Hello');
});
it('falls back when a translation is missing', function () { config()->set('app.fallback_locale', 'en');
$newsItem = NewsItem::create(['name' => ['en' => 'Hello']]);
expect($newsItem->getTranslation('name', 'nl'))->toBe('Hello');
});
三、使用方式 在模型中引入 HasTranslations trait,并通过 #[Translatable] 属性或 $translatable 属性声明可翻译字段;迁移中将对应列设为 json(或 text);随后即可用属性访问、setTranslation/getTranslation 等方法读写翻译,并可用 whereLocale 等查询构造器方法按语言筛选。
四、适用场景 适用于需要在 Eloquent 模型上管理多语言字段的 Laravel 项目,例如新闻、文章、商品等内容的标题与描述多语言存储。
五、限制与常见陷阱
- 迁移中可翻译列必须是 json(或 text)。使用 string 列会在 JSON 转换时抛错。
- 在可翻译属性上直接设置普通字符串只会写入当前语言。要一次设置多个语言,需传入关联数组。
- 不要在 $casts 中为可翻译列注册 array 或 json 转换,HasTranslations 会自行处理 JSON 编码。
- $translatable 属性与 #[Translatable] 属性都是类级别的。运行时修改 $this->translatable 虽然可行,但不常见。
- 当请求的语言缺失时,getTranslation() 会返回回退语言的值。如需严格查找,请使用 getTranslationWithoutFallback()。
关于该扩展包的收费、价格、支持平台等具体信息,资料中暂未提供。