README

语言切换

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

需求

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 Elsayed85/filament-language-switch

用法

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

...
use Elsayed85\FilamentCountrySwitch\CountrySwitch;

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

虽然这已经足够了，但该插件被设计为非常可定制。请查阅下面的配置部分，以获取详细的定制选项。

配置

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

可见性控制

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

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

这两个参数都可以作为 boolean 或返回布尔值的 Closure 提供。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
        ])
        ...;
});
...

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

// 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 Elsayed85\FilamentCountrySwitch\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 的地区标签将自动生成为 巴西葡萄牙语 和 葡萄牙语 (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 将分别标记为 巴西葡萄牙语 和 葡萄牙语 (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
        ])
        ...;
});
...

面板排除

默认情况下，语言切换 将在所有现有面板内可用。但您可以通过提供有效的面板 ID 数组使用 exclude() 方法来选择哪些面板将具有切换器。该方法还接受一个 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() 方法将每个地区与其相应的旗帜图像相关联。数组中的每个键代表地区代码，其值应该是该地区旗帜图像的资产路径。例如，要设置阿拉伯语、法语和英语 (US) 的旗帜图像，您将提供如下所示的数组

//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()
            ...;
    });
    ...

圆形

默认情况下，语言切换 的 Flags 或 Language Badges 略微呈圆形，类似于 Filament 的其他组件。但您可以使用 circular() 方法使其完全圆形。

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

主题

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

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

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

npm run build

视图

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

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

变更日志

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

贡献

如果您想为此包做出贡献，您可能想在真实的 Filament 项目中对其进行测试

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

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

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

现在，运行 composer update。

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

安全漏洞

请参阅我们的安全策略，了解如何报告安全漏洞。

鸣谢

许可

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

elsayed85 / country-switch

维护者

详情