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 上访问您的网站，他们将被重定向到最后一次访问时使用的语言。

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

选择语言的 Widget

安装

通过 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解析期间排除的模式。

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

integready / yii2-localeurls

维护者

详情