SuperAPI AI 工具集

translatable-development

编程与开发

查看项目

更新于 10-16 06:38

技能介绍

spatie/laravel-translatable 是面向 Laravel 的多语言模型扩展包。它的核心设计是把翻译直接以 JSON 形式存储在模型自身的列上,不需要额外的翻译表,也不需要中间表(pivot)。

一、用途 用于让 Eloquent 模型的某些属性支持多语言。当查询涉及可翻译模型、翻译、多语言属性等场景时适用。

二、主要能力

  1. 声明可翻译属性:推荐使用 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'];

}

两者同时存在时,其值会被合并并去重。

  1. 迁移:可翻译列必须是 json 类型(若数据库不支持 json,则用 text)。每个可翻译属性对应一列,该列以 JSON 对象保存所有语言。

Schema::create('news_items', function (Blueprint $table) { $table->id(); $table->json('name')->nullable(); $table->json('description')->nullable(); $table->timestamps(); });

  1. 设置翻译:

// 当前语言(通过 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();

  1. 获取翻译:

// 当前语言 $newsItem->name;

// 指定语言(默认回退到配置的回退语言) $newsItem->getTranslation('name', 'nl');

// 不使用回退 $newsItem->getTranslationWithoutFallback('name', 'nl');

// 某个属性的全部翻译 $newsItem->getTranslations('name'); // ['en' => 'Hello', 'nl' => 'Hallo']

// 所有可翻译属性的全部翻译 $newsItem->translations;

// 该模型拥有翻译的所有语言 $newsItem->locales();

  1. 按语言查询:

// 拥有指定语言翻译的模型 NewsItem::query()->whereLocale('name', 'en')->get();

// 在任一指定语言中有翻译的模型 NewsItem::query()->whereLocales('name', ['en', 'nl'])->get();

// 按翻译值过滤 NewsItem::query()->whereJsonContainsLocale('name', 'en', 'Hello')->get();

  1. 删除翻译:

$newsItem->forgetTranslation('name', 'nl'); // 某个属性的某个语言 $newsItem->forgetTranslations('name'); // 某个属性的所有语言 $newsItem->forgetAllTranslations('nl'); // 所有可翻译属性中的某个语言

  1. 回退行为:默认情况下,当翻译缺失时 getTranslation() 会回退到 config('app.fallback_locale')。可按模型覆盖:

class NewsItem extends Model { use HasTranslations;

public $useFallbackLocale = false; // 为该模型禁用回退

public function getFallbackLocale(): ?string
{
    return 'en'; // 自定义回退语言
}

}

  1. 测试示例:

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 项目,例如新闻、文章、商品等内容的标题与描述多语言存储。

五、限制与常见陷阱

  1. 迁移中可翻译列必须是 json(或 text)。使用 string 列会在 JSON 转换时抛错。
  2. 在可翻译属性上直接设置普通字符串只会写入当前语言。要一次设置多个语言,需传入关联数组。
  3. 不要在 $casts 中为可翻译列注册 array 或 json 转换,HasTranslations 会自行处理 JSON 编码。
  4. $translatable 属性与 #[Translatable] 属性都是类级别的。运行时修改 $this->translatable 虽然可行,但不常见。
  5. 当请求的语言缺失时,getTranslation() 会返回回退语言的值。如需严格查找,请使用 getTranslationWithoutFallback()。

关于该扩展包的收费、价格、支持平台等具体信息,资料中暂未提供。