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 仍然始终使用小写代码。如果使用包含大写代码的 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,
        ]
    ]
];