ahmed-aliraqi / laravel-translatable
Laravel多语言模型包
Requires
- php: >=5.4.0
- illuminate/support: 5.6.*
Requires (Dev)
- orchestra/testbench: 3.6.*
- phpunit/phpunit: ~7.0
This package is auto-updated.
Last update: 2024-08-29 04:42:59 UTC
README
如果您想将模型的翻译存储到数据库中,这个包是给您准备的。
这是一个用于可翻译模型的Laravel包。其目标是简化检索和存储多语言模型实例的复杂性。使用此包,您将编写更少的代码,因为翻译将在您检索/保存实例时自动获取/保存。
文档
演示
获取翻译属性
$greece = Country::where('code', 'gr')->first(); echo $greece->translate('en')->name; // Greece App::setLocale('en'); echo $greece->name; // Greece App::setLocale('de'); echo $greece->name; // Griechenland
保存翻译属性
$greece = Country::where('code', 'gr')->first(); echo $greece->translate('en')->name; // Greece $greece->translate('en')->name = 'abc'; $greece->save(); $greece = Country::where('code', 'gr')->first(); echo $greece->translate('en')->name; // abc
填充多个翻译
$data = [ 'code' => 'gr', 'en' => ['name' => 'Greece'], 'fr' => ['name' => 'Grèce'], ]; $greece = Country::create($data); echo $greece->translate('fr')->name; // Grèce
Laravel兼容性
教程
- 查看laravel-news上关于laravel-translatable的教程:如何为Eloquent添加多语言支持
- 如何为您的Laravel应用程序构建高效且SEO友好的多语言架构
4步安装
步骤1:安装包
通过执行以下命令将包添加到您的composer.json中。
composer require dimsav/laravel-translatable
接下来,将服务提供者添加到app/config/app.php
中
Dimsav\Translatable\TranslatableServiceProvider::class,
步骤2:迁移
在这个例子中,我们想翻译模型Country
。我们需要一个额外的表country_translations
Schema::create('countries', function(Blueprint $table) { $table->increments('id'); $table->string('code'); $table->timestamps(); }); Schema::create('country_translations', function(Blueprint $table) { $table->increments('id'); $table->integer('country_id')->unsigned(); $table->string('name'); $table->string('locale')->index(); $table->unique(['country_id','locale']); $table->foreign('country_id')->references('id')->on('countries')->onDelete('cascade'); });
步骤3:模型
- 可翻译模型
Country
应使用特质Dimsav\Translatable\Translatable
。 - 翻译模型的约定是
CountryTranslation
。
// models/Country.php class Country extends Eloquent { use \Dimsav\Translatable\Translatable; public $translatedAttributes = ['name']; protected $fillable = ['code']; /** * The relations to eager load on every query. * * @var array */ // (optionaly) // protected $with = ['translations']; } // models/CountryTranslation.php class CountryTranslation extends Eloquent { public $timestamps = false; protected $fillable = ['name']; }
数组$translatedAttributes
包含在"Translation"模型中翻译的字段名称。
步骤4:配置
我们将配置文件复制到我们的项目中。
Laravel 5.*
php artisan vendor:publish --tag=translatable
Laravel 4.*
php artisan config:publish dimsav/laravel-translatable
注意:对区域格式的格式没有限制。请随意使用您更喜欢的格式,例如使用"eng"代替"en",或使用"el"代替"gr"。重要的是定义您的区域并坚持使用它们。
配置
配置文件
您可以在配置文件中查看更多自定义选项。
翻译模型
定义翻译模型类的约定是在关键字后附加Translation
。
因此,如果您的模型是\MyApp\Models\Country
,则默认翻译为\MyApp\Models\CountryTranslation
。
要使用自定义类作为翻译模型,请将翻译类(包括命名空间)作为参数定义。例如
<?php namespace MyApp\Models; use Dimsav\Translatable\Translatable; use Illuminate\Database\Eloquent\Model as Eloquent; class Country extends Eloquent { use Translatable; public $translationModel = 'MyApp\Models\CountryAwesomeTranslation'; }
功能列表
请先阅读安装步骤,了解需要创建哪些类。
可用方法
// Before we get started, this is how we determine the default locale. // It is set by laravel or other packages. App::getLocale(); // 'fr' // To use this package, first we need an instance of our model $germany = Country::where('code', 'de')->first(); // This returns an instance of CountryTranslation of using the default locale. // So in this case, french. If no french translation is found, it returns null. $translation = $germany->translate(); // It is possible to define a default locale per model by overriding the model constructor. public function __construct(array $attributes = []) { parent::__construct($attributes); $this->defaultLocale = 'de'; } // It is also possible to define a default locale for our model on the fly: $germany->setDefaultLocale('de'); // If an german translation exists, it returns an instance of // CountryTranslation. Otherwise it returns null. $translation = $germany->translate('de'); // If a german translation doesn't exist, it attempts to get a translation // of the fallback language (see fallback locale section below). $translation = $germany->translate('de', true); // Alias of the above. $translation = $germany->translateOrDefault('de'); // Returns instance of CountryTranslation of using the default locale. // If no translation is found, it returns a fallback translation // if enabled in the configuration. $translation = $germany->getTranslation(); // If an german translation exists, it returns an instance of // CountryTranslation. Otherwise it returns null. // Same as $germany->translate('de'); $translation = $germany->getTranslation('de', true); // To set the translation for a field you can either update the translation model. // Saving the model will also save all the related translations. $germany->translate('en')->name = 'Germany'; $germany->save(); // Alternatively we can use the shortcut $germany->{'name:en'} = 'Germany'; $germany->save(); // There are two ways of inserting mutliple translations into the database // First, using the locale as array key. $greece = $country->fill([ 'en' => ['name' => 'Greece'], 'fr' => ['name' => 'Grèce'], ]); // The second way is to use the following syntax. $greece = $country->fill([ 'name:en' => 'Greece', 'name:fr' => 'Grèce', ]); // Returns true/false if the model has translation about the current locale. $germany->hasTranslation(); // Returns true/false if the model has translation in french. $germany->hasTranslation('fr'); // If a german translation doesn't exist, it returns // a new instance of CountryTranslation. $translation = $germany->translateOrNew('de'); // Returns a new CountryTranslation instance for the selected // language, and binds it to $germany $translation = $germany->getNewTranslation('it'); // The eloquent model relationship. Do what you want with it ;) $germany->translations(); // Remove all translations linked to an object $germany->deleteTranslations(); // Delete one or multiple translations $germany->deleteTranslations('de'); $germany->deleteTranslations(['de', 'en']); // Gel all the translations as array $germany->getTranslationsArray(); // Returns [ 'en' => ['name' => 'Germany'], 'de' => ['name' => 'Deutschland'], 'fr' => ['name' => 'Allemagne'], ]; // Creates a clone and clones the translations $replicate = $germany->replicateWithTranslations();
可用作用域
// Returns all countries having translations in english Country::translatedIn('en')->get(); // Returns all countries not being translated in english Country::notTranslatedIn('en')->get(); // Returns all countries having translations Country::translated()->get(); // Eager loads translation relationship only for the default // and fallback (if enabled) locale Country::withTranslation()->get(); // Returns an array containing pairs of country ids and the translated // name attribute. For example: // [ // ['id' => 1, 'name' => 'Greece'], // ['id' => 2, 'name' => 'Belgium'] // ] Country::listsTranslations('name')->get()->toArray(); // Filters countries by checking the translation against the given value Country::whereTranslation('name', 'Greece')->first(); // Filters countries by checking the translation against the given value, only in the specified locale Country::whereTranslation('name', 'Greece', 'en')->first(); // Or where translation Country::whereTranslation('name', 'Greece')->orWhereTranslation('name', 'France')->get(); // Filters countries by checking the translation against the given string with wildcards Country::whereTranslationLike('name', '%Gree%')->first(); // Or where translation like Country::whereTranslationLike('name', '%eece%')->orWhereTranslationLike('name', '%ance%')->get();
魔法属性
要使用魔法属性,您必须在主模型中定义属性$translatedAttributes
class Country extends Eloquent { use \Dimsav\Translatable\Translatable; public $translatedAttributes = ['name']; }
// Again we start by having a country instance $germany = Country::where('code', 'de')->first(); // We can reference properties of the translation object directly from our main model. // This uses the default locale and is the equivalent of $germany->translate()->name $germany->name; // 'Germany' // We can also quick access a translation with a custom locale $germany->{'name:de'} // 'Deutschland'
回退区域
如果您希望在没有找到翻译时回退到默认翻译,请使用配置中的use_fallback
键启用此功能。要选择默认区域,请使用fallback_locale
键。
配置示例
return [ 'use_fallback' => true, 'fallback_locale' => 'en', ];
您还可以通过设置$useTranslationFallback
属性来为"是否回退"定义每个模型的默认值
class Country { public $useTranslationFallback = true; }
按属性回退
尽管我们尽力将所有模型翻译得很好,但某些字段可能会被留下为空。结果是什么?您将缺少这些字段的翻译!
属性回退功能已在此提供帮助。启用后,可翻译将返回空属性的下级语言的值。
新安装默认启用此功能。如果您的配置文件在v7.1之前设置,请确保添加以下行以启用该功能
'use_property_fallback' => true,
当然,必须启用回退区域设置才能使用此功能。
如果配置中启用了属性回退,则可翻译将返回空翻译的字段的下级区域的翻译。
基于国家的回退
自v5.3版本以来,可以使用基于国家的区域设置。例如,您可以有以下区域设置
- 英语:
en
- 西班牙语:
es
- 墨西哥西班牙语:
es-MX
- 哥伦比亚西班牙语:
es-CO
这些区域的配置如下
'locales' => [ 'en', 'es' => [ 'MX', 'CO', ], ];
我们还可以配置语言和国家之间的“粘合剂”。例如,如果我们更喜欢格式es_MX
而不是es-MX
,则配置应如下所示
'locale_separator' => '_',
对于使用en-MX
格式的区域设置回退,有什么适用?
假设我们的回退区域设置是en
。现在,当我们尝试从数据库中获取es-MX
区域的翻译,但不存在时,我们不会获得回退的en
翻译。可翻译将使用回退es
(es-MX
的第一个部分)和如果找不到任何内容,则返回en
翻译。
翻译自动加载
如果调用toArray()
方法,则可以自动加载所有翻译。为了控制此功能,该包包含一个配置值to_array_always_loads_translations
和特性中的三个静态方法
enableAutoloadTranslations()
- 强制加载所有翻译disableAutoloadTranslations()
- 禁用自动加载并返回父属性defaultAutoloadTranslations()
- 不更改默认行为逻辑(默认)
附加组件
多亏了社区,一些包被编写出来,使得在处理表单时使用可翻译更加容易
常见问题解答
我需要一些示例代码!
我需要帮助!
有任何问题或建议?请随时打开一个问题。
我想帮忙!
你很棒!关注仓库并回复问题。你将帮助为该包的用户提供更好的体验。#communityWorks
此外,通过捐赠为我买一杯啤酒。 ❤️
我在其他特性方法中遇到冲突!
可翻译完全兼容所有类型的Eloquent扩展,包括Ardent。如果您需要帮助将可翻译与这些扩展一起实现,请参阅此示例。
我如何将现有表迁移到使用laravel-translatable?
请参阅安装步骤以了解数据库的结构应该如何。
如果您的属性是用英语编写的,我们建议在迁移中使用以下命令
// We insert the translation attributes into the fresh translated table: \DB::statement("insert into country_translations (country_id, name, locale) select id, name, 'en' from countries"); // We drop the translation attributes in our main table: Schema::table('countries', function ($table) { $table->dropColumn('name'); });
我如何按翻译排序?
这里的一个提示是首先执行MySQL查询,然后执行Eloquent查询。
要获取按翻译字段排序的记录列表,您可以这样做
SELECT * from countries JOIN country_translations as t on t.country_id = countries.id WHERE locale = 'en' GROUP BY countries.id ORDER BY t.name desc
相应的eloquent查询将是
Country::join('country_translations as t', function ($join) { $join->on('countries.id', '=', 't.country_id') ->where('t.locale', '=', 'en'); }) ->groupBy('countries.id') ->orderBy('t.name', 'desc') ->with('translations') ->get();
我如何通过翻译字段选择一个国家?
例如,让我们假设我们想要找到一个国家,其国家翻译名称等于'Portugal'。
Country::whereHas('translations', function ($query) { $query->where('locale', 'en') ->where('name', 'Portugal'); })->first();
您可以在Laravel的查询关系文档中找到更多信息。
为什么在运行迁移时会出现mysql错误?
如果你看到以下mysql错误
[Illuminate\Database\QueryException]
SQLSTATE[HY000]: General error: 1005 Can't create table 'my_database.#sql-455_63'
(errno: 150) (SQL: alter table `country_translations`
add constraint country_translations_country_id_foreign foreign key (`country_id`)
references `countries` (`id`) on delete cascade)
那么你的表使用了MyISAM引擎,该引擎不允许外键约束。MyISAM是5.5版本之前的mysql的默认引擎。从5.5版本开始,默认使用InnoDB存储引擎创建表。
如何修复
对于已创建在生产环境中的表,更新迁移以更改表引擎,然后再添加外键约束。
public function up() { DB::statement('ALTER TABLE countries ENGINE=InnoDB'); } public function down() { DB::statement('ALTER TABLE countries ENGINE=MyISAM'); }
对于新表,一个快速的解决方案是在迁移中设置存储引擎
Schema::create('language_translations', function(Blueprint $table){ $table->engine = 'InnoDB'; $table->increments('id'); // ... });
然而,最好的解决方案是更新你的mysql版本。并且一定要确保开发和生产环境中的版本相同!
捐赠
这款软件是用心和爱制作的。
通过向这个地址发送比特币来表示你的支持和爱:167QC4XQ3acgbwVYWAdmS81jARCcVTWBXU
或者发送到这个PayPal地址:ds@dimsav.com
❤️ 感谢!