README

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

特性

使用此扩展，您可以使用包含语言代码的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 meshzp/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参数中。您应该将更具体的语言代码列在相似外观的通用代码之前（例如，'en-US'在'en'之前）

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

注意：如果您使用国家代码，它们应始终配置为大写字母，如上所示。URL仍然始终使用小写代码。如果使用像en-US这样的带有大写代码的URL，用户将被重定向到小写变体en-us。应用程序语言始终使用正确的en-US代码。

如果您想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。
languageSessionKey：语言会话键的名称。默认为_language。

重置为默认语言

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

答案很简单：为了创建一个重置URL，您必须显式地在URL中包含默认语言的代码。例如，如果默认语言是fr

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

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

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

语言检测

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

要禁用此功能，可以将enableLanguageDetection设置为false。默认启用。

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

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

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

现在假设一个用户第一次访问您的网站。根据他的浏览器设置，他将被重定向到不同的URL。

排除路由/URL

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

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

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

注意：键和值不一定必须相互关联。只是为了方便，配置被组合成一个单独的选项。

meshzp / yii2-localeurls

维护者

详细信息