README

为Yii 2提供通过URL进行自动语言/地区管理的功能。

重要：如果您已从版本1.0.*升级，则必须修改您的配置。请参阅下面的升级部分。

特性

使用此扩展，您可以使用包含语言代码的URL，例如

/en/some/page
/de/some/page
http://www.example.com/en/some/page
http://www.example.com/de/some/page

如果您想的话，还可以配置友好名称

http://www.example.com/english/some/page
http://www.example.com/deutsch/some/page

语言代码会在创建URL时自动添加，并在解析URL时读取。为了获得最佳用户体验，如果没有在URL中使用语言，则会从浏览器设置中自动检测语言。但是，用户仍然可以通过调用具有另一个语言代码的URL来访问其他语言。

最后请求的语言也会持久化到用户会话和cookie中。因此，如果用户尝试访问您的网站而没有在URL中使用语言代码，他们将重定向到最后一次访问时使用的语言。

当然，所有上述内容（以及更多）都是可配置的。

安装

通过composer安装包

composer require codemix/yii2-localeurls

然后将其添加到您的应用程序配置中

<?php
return [

    // ...

    'components' => [
        // ...

        // Override the urlManager component
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',

            // List all supported languages here
            // Make sure, you include your app's default language.
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],
        ]

        // ...
    ]
];

现在您可以开始使用此扩展了。

注意：您仍然可以像往常一样配置自定义URL规则。只需忽略您URL规则中的任何language参数，因为它将在解析之前被删除，并在创建URL之后添加。

注意2：语言代码将从pathInfo中删除。

操作模式及配置

创建URL

所有创建的URL都将包含当前应用程序的语言代码。因此，如果检测到的语言是de，并且您使用

<?php $url = Url::to(['demo/action']) ?>
<?= Html::a('Click', ['demo/action']) ?>

您将获得类似以下URL

/de/demo/action

要创建一个切换应用程序到不同语言的链接，您可以显式添加language URL参数

<?= $url = Url::to(['demo/action', 'language' => 'fr']) ?>
<?= Html::a('Click', ['demo/action', 'language' => 'fr']) ?>

这将为您提供类似以下URL

/fr/demo/action

注意：如果使用自定义URL规则，URL可能看起来不同。在这种情况下，语言参数始终被附加/插入到最后一个相对/绝对URL中。

如果出于某种原因，您想为该URL参数使用不同于language的名称，您可以通过urlManager组件的languageParam选项进行配置。

默认语言

默认语言通过应用程序配置中的language参数进行配置。您必须始终在$languages配置中包含此语言（见下文）。

默认情况下，默认语言的URL不会包含任何语言代码。例如

/
/some/page

如果网站使用包含默认语言代码的URL访问，访客将被重定向到不带语言代码的URL。例如，如果默认语言是fr

/fr/            -> Redirect to /
/fr/some/page   -> Redirect to /some/page

如果将enableDefaultLanguageUrlCode更改为true，则反之亦然。默认语言现在被处理为任何其他配置的语言。不包含语言代码的请求将不再可访问

/fr
/fr/some/page
/               -> Redirect to /fr
/some/page      -> Redirect to /fr/some/page

语言配置

所有语言（包括默认语言）都必须配置在localeUrls组件的languages参数中

'languages' => ['en-US', 'en-UK', 'en', 'fr', 'de-AT', 'de'],

注意： 如果您使用国家代码，它们应始终配置为大写字母，如上所示。URL仍然始终使用小写代码。如果使用类似于en-US的大写代码，用户将被重定向到小写变体en-us。应用程序语言将始终使用正确的en-US代码。如果您不想重定向带有小写国家代码的URL，可以将keepUppercaseLanguageCode选项设置为true。

如果您希望您的URL可选地包含任何国家变体，您也可以使用通配符模式

'languages' => ['en-*', 'de-*'],

现在，任何匹配en-??或de-??的URL都可以使用，例如en-us或de-at。没有国家代码的URL，如en和de，也将继续工作

/en/demo/action
/en-us/demo/action
/en-en/demo/action
/de/demo/action
/de-de/demo/action
/de-at/demo/action

带有国家代码的URL将设置完整的ll-CC代码作为Yii语言，而只有语言代码的URL将导致使用配置的语言的ll。

注意： 如果您只想将浏览器设置中检测到的语言从de-AT回退到de，则不需要此功能。请参阅下面的语言检测部分。

您还可以在URL中使用更友好的名称或别名，配置如下

'languages' => ['en', 'german' => 'de', 'br' => 'pt-BR'],

<?= Url::to(['demo/action', 'language' => 'de']) ?>

这将为您提供如下URL

/german/demo/action
/br/demo/action

并将匹配的相应语言设置为de或pt-PR。

持久性

访问者最后使用的语言将被存储在用户会话和cookie中。如果用户在没有语言代码的情况下再次访问您的网站，他将被重定向到存储的语言。

例如，如果用户首先访问

/de/some/page

然后一段时间后返回以下URL之一

/some/page      -> Redirect to /de/some/page
/               -> Redirect to /de/
/dk/some/page

在最后一种情况下，dk将被存储为最后使用的语言。

持久性默认启用，可以通过将localeUrls组件中的enableLanguagePersistence设置为false来禁用。

您可以使用以下方式修改其他持久性设置

• languageCookieDuration：在cookie中存储语言信息的时间（以秒为单位）。设置为false以禁用cookie。
• languageCookieName：语言cookie的名称。默认为_language。
• languageCookieOptions：设置在语言cookie上的其他选项。
• languageSessionKey：语言会话键的名称。默认为_language。从1.6.0版本开始，也可以将其设置为false以完全使用会话。

重置为默认语言

您会注意到，如果enableDefaultLanguageUrlCode设置为false（默认值）并且用户已将de存储为最后使用的语言，那么将存在一个问题。我们如何现在以默认语言访问网站？因为如果我们尝试/，我们会被重定向到/de/。

答案是简单的：要创建重置URL，您需要在URL中显式包含默认语言的代码。例如，如果默认语言是fr

<?= Url::to(['demo/action', 'language' => 'fr']) ?>

/fr/demo/action -> Redirect to /demo/action

在这种情况下，fr将被首先存储为最后使用的语言，然后用户将被重定向。

如果您需要显式创建不带任何语言代码的默认语言URL，您也可以传递一个空字符串作为语言

<?= Url::to(['demo/action', 'language' => '']) ?>

这将为您提供

/demo/action

语言更改事件

当启用持久性时，组件将在会话或cookie中存储的语言更改时触发languageChanged事件。以下是一个示例，说明如何使用它来跟踪数据库中的用户语言

<?php

'urlManager' => [
    'class' => 'codemix\localeurls\UrlManager',
    'languages' => ['en', 'fr', 'de'],
    'on languageChanged' => `\app\components\User::onLanguageChanged',
]

User中的静态类方法可能看起来像这样

<?php
public static function onLanguageChanged($event)
{
    // $event->language: new language
    // $event->oldLanguage: old language

    // Save the current language to user record
    $user = Yii::$app->user;
    if (!$user->isGuest) {
        $user->identity->language = $event->language;
        $user->identity->save();
    }
}

注意：语言可能在用户登录或注册之前就已经被选择。因此，在这些情况下，您也应该保存或更新语言。

语言检测

如果用户首次访问您的网站且会话或cookie中没有存储语言（或者持久化已关闭），则将根据访问者的浏览器设置检测语言。如果首选语言之一与您的语言匹配，则将其用作应用程序语言（如果启用持久化，则会持久化）。

要禁用此功能，可以将enableLanguageDetection设置为false。默认情况下是启用的。

如果浏览器语言包含国家代码，如de-AT，而您在$languages配置中只有de，则将回退到该语言。只有当您使用了通配符如de-*或明确配置了de-AT或别名如'at' => 'de-AT'时，包括国家代码的浏览器语言才会被使用。

让我们通过一个示例配置来更好地了解，$languages配置如何影响语言检测和创建的URL。

'languages' => [
  'en',
  'at' => 'de-AT',
  'de',
  'pt-*'
],

现在假设用户首次访问您的网站。根据他的浏览器设置，他将被导向不同的URL。

通过GeoIP服务器模块进行检测

从1.7.0版本开始，语言也可以通过web服务器的GeoIP模块进行检测。请注意，这仅在浏览器设置中没有找到有效语言时才会发生。

为了使此功能正常工作，相关的GeoIp模块必须已经安装，并且它必须提供国家代码作为服务器变量中的$_SERVER。您可以在$geoIpServerVar中配置键。默认值为HTTP_X_GEO_COUNTRY。

要启用此功能，您必须提供一个GeoIp国家代码列表，并按相应的语言索引

'geoIpLanguageCountries' => [
    'de' => ['DEU', 'AUT'],
    'pt' => ['PRT', 'BRA'],
],

排除路由/URL

您可能想使用$ignoreLanguageUrlPatterns选项禁用某些路由和URL的语言处理。

<?php
    'ignoreLanguageUrlPatterns' => [
        // route pattern => url pattern
        '#^site/(login|register)#' => '#^(signin|signup)#',
        '#^api/#' => '#^api/#',
    ],

键和值都是正则表达式。键是匹配要排除从URL创建期间语言处理的路由的模式，而值是应该排除在URL解析期间的pathInfo模式。

注意：键和值不必相互关联。这只是为了方便，将配置组合成单个选项。

示例语言选择小部件

没有包含语言选择小部件，因为这样的小部件的标记和行为有太多的选项。但它很容易构建。以下是一个基本思路

<?php
use Yii;
use yii\bootstrap\Dropdown;

class LanguageDropdown extends Dropdown
{
    private static $_labels;

    private $_isError;

    public function init()
    {
        $route = Yii::$app->controller->route;
        $appLanguage = Yii::$app->language;
        $params = $_GET;
        $this->_isError = $route === Yii::$app->errorHandler->errorAction;

        array_unshift($params, '/' . $route);

        foreach (Yii::$app->urlManager->languages as $language) {
            $isWildcard = substr($language, -2) === '-*';
            if (
                $language === $appLanguage ||
                // Also check for wildcard language
                $isWildcard && substr($appLanguage, 0, 2) === substr($language, 0, 2)
            ) {
                continue;   // Exclude the current language
            }
            if ($isWildcard) {
                $language = substr($language, 0, 2);
            }
            $params['language'] = $language;
            $this->items[] = [
                'label' => self::label($language),
                'url' => $params,
            ];
        }
        parent::init();
    }

    public function run()
    {
        // Only show this widget if we're not on the error page
        if ($this->_isError) {
            return '';
        } else {
            return parent::run();
        }
    }

    public static function label($code)
    {
        if (self::$_labels === null) {
            self::$_labels = [
                'de' => Yii::t('language', 'German'),
                'fr' => Yii::t('language', 'French'),
                'en' => Yii::t('language', 'English'),
            ];
        }

        return isset(self::$_labels[$code]) ? self::$_labels[$code] : null;
    }
}

升级

从1.0.*到1.1.*的变更

如果您从1.0.*版本升级，您将需要修改您的配置。现在不再有localeUrls组件了。相反，一切都被合并到了我们的自定义urlManager组件中。因此，您应该将任何针对localeUrls组件的配置移动到urlManager组件中。

两个选项也已被重命名，以提高清晰度

• enableDefaultSuffix现在为enableDefaultLanguageUrlCode
• enablePersistence现在为enableLanguagePersistence

因此，如果您的配置如下所示

<?php
return [
    'bootstrap' => ['localeUrls'],
    'components' => [
        'localeUrls' => [
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],
            'enableDefaultSuffix' => true,
            'enablePersistence' => false,
        ],
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',
        ]
    ]
];

您现在应该将其更改为

<?php
return [
    'components' => [
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],
            'enableDefaultLanguageUrlCode' => true,
            'enableLanguagePersistence' => false,
        ]
    ]
];