README

本包提供了一种强大且透明的管理Eloquent多语言模型的方法。

它利用了Laravel的增强全局范围，将翻译属性连接到每个查询，而不是像某些替代包那样使用关系。因此，只需要一个查询就可以获取翻译属性，无需为翻译表创建单独的模型，这使得本包更容易使用。

快速演示
版本
安装
- Laravel中的配置
- 非Laravel中的配置
创建迁移
配置模型
CRUD操作
翻译作为关系
作者和维护
许可协议

快速演示

为了在模型中启用翻译，您首先需要根据约定准备您的模式。之后，您可以将Translatable特性引入。

use Laraplus\Data\Translatable;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use Translatable;
}

这就完成了！无需其他配置。翻译属性将被自动缓存，所有查询都将返回翻译属性。

Post::first();
$post->title; // title in the current locale

Post::translateInto('de')->first();
$post->title; // title in 'de' locale

Post::translateInto('de')->withFallback('en')->first();
$post->title; // title in 'de' if available, otherwise in 'en'

由于翻译属性连接到查询，因此过滤和按翻译属性排序也非常容易。

Post::where('body', 'LIKE', '%Laravel%')->orderBy('title', 'desc');

甚至可以只返回翻译记录。

Post::onlyTranslated()->all()

所有基本CRUD操作都提供了多种辅助工具。有关所有可用选项，请参阅下面的完整文档。

版本

安装

本包可用于Laravel或Lumen应用程序，以及任何其他利用Laravel数据库组件https://github.com/illuminate/database的应用程序。通过composer安装此包。

composer require spletna-postaja/translatable

Laravel中的配置

尽管您可以在/config/app.php配置文件的providers键下手动添加服务提供程序，但本包将在Laravel中自动发现。

'providers' => [
    // Other providers
    Laraplus\Data\TranslatableServiceProvider::class,
],

您可以通过发布translatable.php配置文件来配置一些其他选项。

php artisan vendor:publish --provider="Laraplus\Data\TranslatableServiceProvider" --tag="config"

打开配置文件以查看所有可用设置：https://github.com/spletna-postaja/translatable/blob/master/config/translatable.php

非Laravel中的配置

在Laravel之外使用此包时，您可以使用TranslatableConfig类进行配置。

TranslatableConfig::currentLocaleGetter(function() {
    // Return the current locale of the application
});

TranslatableConfig::fallbackLocaleGetter(function() {
    // Return the fallback locale of the application
});

您还可以调整一些其他设置。要查看所有可用选项，请检查Laravel的服务提供程序：https://github.com/spletna-postaja/translatable/blob/master/src/TranslatableServiceProvider.php

创建迁移

要利用多语言模型，您需要以特定方式准备数据库表。每个可翻译的表都由可翻译属性和非可翻译属性组成。虽然您可以将非可翻译属性正常添加到表中，但可翻译字段需要放在自己的表中，表名应遵循约定。

以下是一个针对posts表的示例迁移：

Schema::create('posts', function(Blueprint $table)
{
    $table->increments('id');
    $table->datetime('published_at');
    $table->timestamps();
});

Schema::create('posts_i18n', function(Blueprint $table)
{
    $table->integer('post_id')->unsigned();
    $table->string('locale', 6);
    $table->string('title');
    $table->string('body');
    
    $table->primary(['post_id', 'locale']);
});

默认情况下，翻译表必须以 _i18n 后缀结尾，尽管这可以在之前提到的配置文件中更改。翻译表必须始终包含对父表的引用外键以及一个 locale 字段（也可配置），该字段将存储翻译属性的本地化版本。不允许在翻译模型上使用递增键。需要定义一个包含 locale 和对父模型的外键引用的复合键。可选地，您可以定义外键约束，但该包也可以在没有它们的情况下运行。

重要：确保没有翻译属性与任何非翻译属性具有相同的名称，因为这会破坏查询。这也适用于时间戳（不应添加到翻译表中，而应仅添加到主表中）和递增键（不允许在翻译表中）。

配置模型

要使模型了解翻译属性，您需要引入 Translatable 特性

use Laraplus\Data\Translatable;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use Translatable;
}

可选地，您可能需要定义一个包含 $translatable 属性的数组，但该包设计为无需它即可运行。在这种情况下，翻译属性将从数据库模式自动确定并无限期缓存。如果您正在使用缓存方法，不要忘记在每次更改模式时清除缓存。

默认情况下，如果模型未翻译成当前区域设置，将选择回退翻译。如果没有可用的翻译，所有可翻译属性都将返回 null。如果您想更改这种行为，可以修改 translatable.php 配置文件或按“模型”级别调整行为

class Post extends Model
{
    use Translatable;
    
    protected $withFallback = false;
    
    protected $onlyTranslated = true;
}

CRUD操作

选择行

要选择可翻译模型中的行，您可以使用所有常规的 Eloquent 查询辅助函数。可翻译属性将以您的当前区域设置返回。有关如何在 Laravel 中配置本地化的更多信息，请参阅官方文档：https://laravel.net.cn/docs/6.0/localization

Post::where('active', 1)->orderBy('title')->get();

查询辅助函数

默认情况下，上述查询还将返回当前或回退区域设置中没有任何翻译的记录。要仅返回已翻译的行，您可以更改 defaults.only_translated 配置选项为 true，或使用 onlyTranslated() 查询辅助函数

Post::onlyTranslated()->get();

有时您可能希望完全禁用回退翻译。为此，您可以更改 defaults.with_fallback 配置选项为 false 或使用 withoutFallback() 查询辅助函数

Post::withoutFallback()->get();

上述两个辅助函数都有其对立形式：withUntranslated() 和 withFallback()。您还可以为 withFallback() 辅助函数提供一个可选的 $locale 参数，以更改默认的回退区域设置

Post::withUntranslated()->withFallback()->get();
Post::withUntranslated()->withFallback('de')->get();

有时您可能希望以与当前区域设置不同的区域设置检索翻译。为此，您可以使用 translateInto($locale) 辅助函数

Post::translateInto('de')->get();

如果您根本不需要翻译属性，您可以使用 withoutTranslations() 辅助函数，这将从查询中删除可翻译的全局作用域

Post::withoutTranslations()->get();

根据翻译属性进行过滤和排序

通常，您可能希望根据翻译属性过滤查询结果。该包允许您使用所有常规的 Eloquent where 子句。这将与回退翻译一起工作，因为 where 子句中的所有列都将自动使用 ifnull 语句包装，并使用适当的表名作为前缀

Post::where('title', 'LIKE', '%Laravel%')->orWhere('description', 'LIKE', '%Laravel%')->get();

相同的逻辑也适用于 order by 子句，它也将自动转换为正确的格式

Post::orderBy('title')->get();

注意：如果您正在使用whereRaw子句，由于我们无法解析whereRaw表达式，我们将无法自动格式化您的表达式。相反，您需要手动包含适当的表前缀。

插入行

在当前区域设置中创建新模型时，您可以使用正常的Laravel语法，就像您正在向单个表中插入行一样。

Post::create([
    'title'        => 'My title',
    'published_at' => Carbon::now(),
]);

如果您想将记录存储在替代区域设置中，可以使用createInLocale($locale, $attributes)辅助函数。

Post::createInLocale('de', [
    'title'        => 'Title in DE',
    'published_at' => Carbon::now(),
]);

通常，您需要将新记录与所有翻译一起存储。为此，您可以将可翻译属性作为create()方法的第二个参数列出。

Post::create([
    'published_at' => Carbon::now()
], [
    'en' => ['title' => 'Title in EN'],
    'de' => ['title' => 'Title in DE'],
]);

上述所有辅助函数也有它们的force形式，允许您绕过大量赋值保护。

Post::forceCreate([/*attributes*/], [/*translations*/]);
Post::forceCreateInLocale($locale, [/*attributes*/]);

更新行

在当前区域设置中更新记录就像更新单个表一样简单。

$user = User::first();

$user->title = 'New title';
$user->save();

如果您希望更新另一个区域设置中的记录，可以使用saveTranslation($locale, $attributes)辅助函数，该函数将更新现有翻译或创建新的（如果尚不存在）。

$user = User::first();

$user->saveTranslation('en', [
    'title' => 'Title in EN'
]);

$user->saveTranslation('de', [
    'title' => 'Title in DE'
]);

还有一个forceSaveTranslation($locale, $attributes)辅助函数可用于绕过大量赋值保护。

要一次性更新多行，您也可以使用查询构建器。

User::where('published_at', '>', Carbon::now())->update(['title' => 'New title']);

要使用查询构建器更新不同的区域设置，您可以调用transleteInto($locale)辅助函数。

User::where('published_at', '>', Carbon::now())->translateInto('de')->update(['title' => 'New title']);

删除行

删除行非常简单。像往常一样操作，翻译将与父行一起自动删除。

$user = User::first();

$user->delete();

要一次性删除多行，您也可以使用查询构建器。翻译将自动清理。

User::where('published_at', '>', Carbon::now())->delete();

翻译作为关系

有时，您可能希望检索特定模型的全部翻译。幸运的是，该包实现了一个hasMany关系，这可以帮助您做到这一点。

$user = $user->first();

foreach ($user->translations as $translation) {
    echo "Title in {$translation->locale}: {$translation->title}";
}

当您希望访问特定区域的属性时，有一个translate($locale)辅助函数可用。

$user = $user->first();

$user->translate('en')->title; // Title in EN
$user->translate('de')->title; // Title in DE

在使用关系时，您通常希望预加载它而无需将翻译属性连接到查询中。有一个withAllTranslations()辅助函数可用于此目的。

User::withAllTranslations()->get();

注意：目前对使用关系更新和插入新记录的支持有限。相反，您可以使用上面描述的辅助函数。

作者和维护

本项目的作者和主要开发者是Anže Časar。

该项目由Spletna postaja支持并维护，这是一家网络开发公司。

该项目由Spletna postaja支持并维护，这是一家开发和制作网站以及制作网店的公司。

许可协议

该项目是开源软件，许可协议为MIT许可证。

spelnapostaja / translatable

维护者

详细信息