README

语言切换

语言切换插件是一个多功能且用户友好的工具，专为Filament Panels设计。它提供了一种无缝集成语言切换功能的方式。具有一系列可定制的选项和流畅的API，该插件允许您轻松配置用户的语言选择。它支持在Filament面板内部和外部显示语言选项，并提供了灵活性，可以指定哪些面板或路由应包括语言切换以及其他更多功能。

要求

filament v3

注意

对于filament v2，请使用v1

重要

从2.x迁移到3.x

从所有面板中注销插件
删除配置文件config/filament-language-switch.php
从resources/views/vendor中删除filament-language-switch目录
在您的composer.json文件中将包版本提升到^3.0
运行composer update
查看下面的使用部分以开始使用。
查看下面的配置部分以了解新功能和如何配置插件。

安装

通过composer安装包

composer require bezhansalleh/filament-language-switch

使用

插件安装后自动启动。为了使插件工作，请在服务提供者的boot()方法中提供支持的语言区域数组以在面板之间切换。您可以选择创建一个新的服务提供者或使用默认的AppServiceProvider，如下所示

...
use BezhanSalleh\FilamentLanguageSwitch\LanguageSwitch;

class AppServiceProvider extends ServiceProvider
{
    ...
    
    public function boot()
    {
        ...
        
        LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
            $switch
                ->locales(['ar','en','fr']); // also accepts a closure
        });
        
        ...
    }
}

尽管这是您需要做的所有事情，但该插件设计得非常可定制。请查看下面的配置部分以获取详细的定制选项。

配置

该插件包含以下选项，您可以根据需要自定义和配置。该插件具有流畅的API，因此您可以通过链式方法在单个位置轻松配置所有内容。

可见性控制

visible()方法配置应用程序UI中语言切换的可见性。它有两个参数

insidePanels：确定语言切换器是否在Filament面板内部可见，默认为true。只有当insidePanels条件为真、存在多个区域，并且当前面板包含时（不是排除），语言切换器才会在面板内部可见。
outsidePanels：控制面板外的可见性，默认为false。只有当outsidePanels条件为真、当前路由包含在outsidePanelRoutes()中，并且当前面板包含时（不是排除），语言切换器才会在面板外可见。

这两个参数可以提供为boolean或返回布尔值的Closure。闭包允许动态确定可见性，使您能够根据应用程序状态、用户权限或其他标准包含复杂的逻辑。

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->visible(outsidePanels: true)
            ...;
    });
    ...

外部面板路由

outsidePanelRoutes() 方法用于定义 语言切换 应该在 Filament 面板外部可见的路由。此方法接受一个 array 路由名称数组或一个返回路由名称数组的 Closure。默认情况下，它包括常见的身份验证路由，如 auth.login、auth.profile 和 auth.register。

要指定用于显示语言切换器的自定义路由，请向方法传递路由名称数组

// AppServiceProvider.php
...
LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
    $switch
        ...
        ->outsidePanelRoutes([
            'profile',
            'home',
            // Additional custom routes where the switcher should be visible outside panels
        ])
        ...;
});
...

如果您想动态确定路由，请使用 Closure

// AppServiceProvider.php
...
LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
    $switch
        ...
        ->outsidePanelRoutes(fn() => someCondition() ? ['dynamic.route'] : ['default.route'])
        ...;
});
...

外部面板位置

outsidePanelPlacement() 方法用于指定 语言切换 在渲染在 Filament 面板外部时的位置。此方法接受一个 Placement 枚举值，该值确定开关在屏幕上的位置。

您可以从以下在 Placement 枚举中定义的位置中选择

TopLeft 默认
TopCenter
TopRight
BottomLeft
BottomCenter
BottomRight

像这样设置外部 Filament 面板上的 语言切换 的期望位置

// AppServiceProvider.php
...
use BezhanSalleh\FilamentLanguageSwitch\Enums\Placement;

LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
    $switch
        ...
        ->outsidePanelPlacement(Placement::BottomRight)
        // Sets the language switch to appear at the bottom right outside of panels
        ...;
});
...

本地化标签

displayLocale() 方法用于设置影响 PHP 原生函数 locale_get_display_name() 生成的给定地区标签的本地。此方法指定当未使用 labels() 方法设置自定义标签时，给定地区的标签应显示的语言。

默认情况下，如果未显式设置 displayLocale()，则地区标签根据应用程序的当前本地生成。这影响未设置自定义标签的地区自动标签生成。

例如，如果您的应用程序的当前本地为 英语 ('en')，并且您没有设置特定的显示本地，那么像 pt_BR 和 pt_PT 这样的地区标签将自动生成为 Portuguese (Brazil) 和 Portuguese (Portugal)，分别为英语。

要指定用于自动标签生成的不同语言，请使用 displayLocale()

// AppServiceProvider.php
...
LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
    $switch
        ...
        ->displayLocale('fr') // Sets French as the language for label localization
        ...;
});
...

自定义标签

语言切换 中的 labels() 方法允许您为应用程序支持的每个地区定义自定义文本标签。这种定制在 PHP 原生函数 locale_get_display_name() 生成的默认标签不适合您的应用程序需求时非常有用。

默认情况下，如果没有提供自定义标签，语言切换 将使用原生 PHP 函数 locale_get_display_name() 为每个地区生成标签，该函数根据当前应用程序的本地创建标签。例如，当应用程序的本地设置为 en 时，地区 pt_BR 和 pt_PT 将分别标记为 Portuguese (Brazil) 和 Portuguese (Portugal)。

但是，您可能希望显示更短或不同格式的标签。这就是 labels() 方法的好处。您可以指定每种语言应该如何标记，从而覆盖默认行为。

这是设置自定义标签的方法

// AppServiceProvider.php
...
LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
    $switch
        ...
        ->locales(['en','fr','pt_BR','pt_PT'])
        ->labels([
            'pt_BR' => 'Português (BR)',
            'pt_PT' => 'Português (PT)',
            // Other custom labels as needed
        ])
        ...;
});
...

面板排除

默认情况下，语言切换 将在所有现有面板中可用。但您可以通过使用 exclude() 方法提供有效的面板 id 数组来选择哪些面板将包含切换器。此方法还接受一个 Closure，因此您可以对排除某些面板有更多控制。

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->excludes([
                'app'
            ])
            ...;
    });
    ...

渲染钩子

默认情况下，使用 panels::global-search.after 钩子来渲染 语言切换。但您可以使用 Filament 中的任何渲染钩子，通过 renderHook() 方法使用，如下所示

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->renderHook('panels::global-search.before')
            ...;
    });
    ...

旗帜

默认情况下，语言切换使用地区作为语言徽章作为旗帜的占位符。但您可以通过传递一个数组到flags()方法来将每个地区与其相应的旗帜图像关联起来。数组中的每个键代表地区代码，其值应该是该地区旗帜图像的资产路径。例如，要为阿拉伯语、法语和英语（美国）设置旗帜图像，您将提供一个如下所示的数组

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->flags([
                'ar' => asset('flags/saudi-arabia.svg'),
                'fr' => asset('flags/france.svg'),      
                'en' => asset('flags/usa.svg'),
            ])
            ...;
    });
    ...

请确保在asset()辅助函数中提供的路径指向您的Laravel项目公共目录中旗帜图像的正确位置。

仅旗帜

flagsOnly()方法控制语言切换是否仅显示旗帜图像，而不显示伴随的文本标签。此方法可以通过提供更简洁的界面，在空间有限或您更喜欢更直观的语言选项表示时增强UI。

要仅显示每种语言的旗帜，调用此方法并确保您已使用flags()方法提供了如上所示的地区旗帜

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->flags([
                'ar' => asset('flags/saudi-arabia.svg'),
                'fr' => asset('flags/france.svg'),      
                'en' => asset('flags/usa.svg'),
            ])
            ->flagsOnly()
            ...;
    });
    ...

圆形

默认情况下，语言切换的旗帜或语言徽章略微圆润，类似于大多数其他Filament组件。但您可以使用circular()方法将其完全圆润。

//AppServiceProvider.php
    ...
    LanguageSwitch::configureUsing(function (LanguageSwitch $switch) {
        $switch
            ...
            ->circular()
            ...;
    });
    ...

主题

此插件遵循Filament的主题规则。因此，如果您有自定义主题，请将插件的视图路径添加到主题的tailwind.config.js文件中的content数组中

//tailwind.config.js
export default {
    content: [
        // ...
        './vendor/bezhansalleh/filament-language-switch/resources/views/language-switch.blade.php',
    ],
    // ...
}

...现在使用以下命令构建您的主题

npm run build

视图

如果您想调整设计，可以使用以下命令发布视图，并按您的喜好进行调整

php artisan vendor:publish --tag="filament-language-switch-views"

变更日志

有关最近更改的更多信息，请参阅变更日志

贡献

如果您想为此包做出贡献，您可能想在一个真实的Filament项目中测试它

将此存储库Fork到您的GitHub帐户。
在本地创建一个Filament应用。
在Filament应用的根目录中克隆您的Fork。
在/filament-language-switch目录中，为您的修复创建一个分支，例如fix/error-message。

在您的应用的composer.json中安装包

"require": {
    "bezhansalleh/filament-language-switch": "dev-fix/error-message as main-dev",
},
"repositories": [
    {
        "type": "path",
        "url": "filament-language-switch"
    }
]

现在，运行composer update。

有关详细信息，请参阅贡献指南

安全漏洞

请查看我们关于如何报告安全漏洞的安全策略

鸣谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件

bezhansalleh / filament-language-switch

维护者

详细信息