Voyager 多语言功能深度解析：从配置到实战-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00194/article/details/148393554

Voyager 多语言功能深度解析：从配置到实战

voyager 项目地址: https://gitcode.com/gh_mirrors/voy/voyager

前言

在当今全球化互联网环境下，多语言支持已成为现代Web应用的基本需求。Voyager作为一款功能强大的后台管理系统，提供了完善的多语言解决方案。本文将全面解析Voyager的多语言功能实现原理和使用方法，帮助开发者快速构建国际化应用。

一、多语言基础配置

1.1 启用多语言功能

首先需要在配置文件中进行基础设置：

// config/voyager.php
'multilingual' => [
    'enabled' => true,       // 启用多语言功能
    'default' => 'en',       // 设置默认语言
    'locales' => [           // 支持的语言列表
        'en',                // 英语
        'da',               // 丹麦语
        // 可添加更多语言
    ],
],

1.2 模型配置

要使模型支持多语言，需要两个关键步骤：

使用Translatable Trait
定义可翻译字段

use TCG\Voyager\Traits\Translatable;

class Post extends Model
{
    use Translatable;
    
    // 指定哪些字段需要多语言支持
    protected $translatable = ['title', 'body', 'meta_description'];
}

配置完成后，在后台管理界面中会自动显示语言选择器。

二、多语言数据操作

2.1 数据查询优化

Voyager提供了多种方式高效加载翻译数据：

// 方法1：预加载所有翻译
$posts = Post::with('translations')->get();

// 方法2：查询后加载翻译
$posts = Post::all();
$posts->load('translations');

// 方法3：使用快捷方法
$posts = Post::withTranslations()->get();

// 方法4：加载指定语言翻译
$posts = Post::withTranslations(['en', 'da'])->get();

// 方法5：加载单个语言翻译
$posts = Post::withTranslation('da')->get();

2.2 数据读取方式

获取翻译数据有多种灵活的方式：

// 获取默认语言的值
echo $post->title;

// 获取指定语言的翻译（完整参数）
echo $post->getTranslatedAttribute('title', 'da', 'en');

// 获取当前语言的翻译（简化版）
echo $post->getTranslatedAttribute('title');

参数说明：

第一个参数：字段名
第二个参数（可选）：目标语言，默认使用当前应用语言
第三个参数（可选）：回退语言，默认使用应用回退语言
设置第三个参数为false可禁用回退机制

2.3 整模型翻译

可以一次性翻译整个模型：

// 翻译单个模型
$translatedPost = $post->translate('da');
echo $translatedPost->title;

// 翻译集合中的所有模型
$translatedPosts = $posts->translate('da');
echo $translatedPosts[0]->title;

三、高级功能与技巧

3.1 模型可翻译性检测

在不确定模型是否支持多语言时，可以进行检测：

// 通过类名检测
if (Voyager::translatable(Post::class)) {
    // 处理多语言逻辑
}

// 通过模型实例检测
if (Voyager::translatable($post)) {
    // 处理多语言逻辑
}

3.2 翻译数据写入

更新或创建翻译数据：

$post = $post->translate('da');  // 准备丹麦语翻译
$post->title = '新标题';         // 设置翻译内容
$post->save();                   // 保存翻译

重要提示：如果修改的字段未在$translatable中定义，修改将直接作用于默认语言版本。

3.3 翻译数据查询

Voyager提供了专门的翻译查询方法：

// 基本查询
$page = Page::whereTranslation('slug', 'my-slug')->first();

// 带操作符的查询
$page = Page::whereTranslation('slug', '=', 'my-slug');

// 限定查询语言范围
$page = Page::whereTranslation('slug', 'my-slug', ['en', 'da']);

// 排除默认语言查询
$page = Page::whereTranslation('slug', 'my-slug', ['en', 'da'], false);

参数详解：