etchfoda/laravel-translatable

Laravel多语言模型包

维护者

详细信息

github.com/etchfoda/laravel-translatable

源代码

问题

安装: 36

依赖者: 0

建议者: 0

安全性: 0

星级: 1

关注者: 0

分支: 320

开放问题: 0

v11.0.0 2021-10-15 09:24 UTC

Requires

Requires (Dev)

MIT 9da349fc6c54df1390c72517b8d083d63f44a25d

databasetranslationlanguagelaravel

This package is auto-updated.

Last update: 2024-09-15 16:02:32 UTC

README

此包已被弃用。[查看详情]。但无需担心，您可以使用Astrotomic/laravel-translatable.

Laravel-Translatable

Total Downloads Build Status Code Coverage Latest Stable Version License SensioLabsInsight StyleCI

Laravel Translatable

如果您想将模型的翻译存储到数据库中，这个包就是为您准备的。

这是一个针对可翻译模型的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兼容性

教程

4步安装

步骤1：安装包

通过执行以下命令将包添加到您的composer.json中。

composer require etchfoda/laravel-translatable

接下来，将服务提供者添加到app/config/app.php

Etchfoda\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：模型

  1. 可翻译模型Country应该使用特质 Etchfoda\Translatable\Translatable。
  2. 翻译模型的约定为CountryTranslation。
// models/Country.php
class Country extends Eloquent {
    
    use \Etchfoda\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 etchfoda/laravel-translatable

注意：对区域格式的限制没有任何限制。请随意使用最适合您的格式，例如使用"eng"而不是"en"，或使用"el"而不是"gr"。重要的是定义您的区域并坚持使用。

配置

配置文件

您可以在配置文件中查看更多自定义选项。

翻译模型

定义翻译模型类的约定是在类名后附加关键字Translation。

因此，如果您的模型是\MyApp\Models\Country，默认翻译将是\MyApp\Models\CountryTranslation。

如果您想使用自定义类作为翻译模型，请将包含命名空间的翻译类定义为参数。例如

<?php 

namespace MyApp\Models;

use Etchfoda\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 \Etchfoda\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,

当然，必须启用回退区域设置才能使用此功能。

如果配置中启用了属性回退，则可翻译将返回空翻译的字段回退区域的翻译。

自定义空翻译属性检测

这个包是为了翻译字符串，但通常它也能翻译数字、布尔值或您想要的任何内容。默认情况下，使用简单的 empty() 调用来检测翻译值是否为空。如果您想自定义此功能或为每个属性使用不同的逻辑，您可以在主模型中覆盖 isEmptyTranslatableAttribute()。

protected function isEmptyTranslatableAttribute(string $key, $value): bool
{
    switch($key) {
        case 'name':
            return empty($value);
        case 'price':
            return !is_number($value);
        default:
            return is_null($value);
    }
}

基于国家的回退

从版本 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() - 不更改默认行为逻辑（默认）

附加组件

感谢社区，一些包已被编写，以便在处理表单时使使用 Translatable 更容易

常见问题解答

我需要一些示例代码！

所有包功能的示例可以在用于测试的代码中找到。

我需要帮助！

有任何问题或建议？请随时创建问题。

我想帮助！

您很棒！关注仓库并回复问题。您将帮助为包的用户提供更好的体验。 #communityWorks

此外，通过进行捐赠为我买杯啤酒。 ❤️

我遇到了与其他特质方法冲突的问题！

Translatable完全兼容所有Eloquent扩展，包括Ardent。如果您需要帮助将这些扩展与Translatable结合使用，请参阅此示例。

如何将现有的表迁移到使用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地址发送： admin@etchfoda.com

❤️ 感谢您！