# UrlLanguageManager

> Resolves the application language from a URL code, the persisted choice, the browser, or GeoIP, and adds the language code to created URLs.

[API reference](/docs/api/index.md) › [Locale URLs](/docs/extensions/localeurls/reference/index.md) › UrlLanguageManager

| class | `yii2\extensions\localeurls\UrlLanguageManager` |
| --- | --- |
| Extends | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) » [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Source | [`src/UrlLanguageManager.php`](https://github.com/yii2-extensions/localeurls/blob/main/src/UrlLanguageManager.php#L54) |

Resolves the application language from a URL code, the persisted choice, the browser, or GeoIP, and adds the language
code to created URLs.

A URL without a code redirects to the persisted or detected language; a URL with the default language code redirects
to the URL without it unless [`$enableDefaultLanguageUrlCode`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enableDefaultLanguageUrlCode) is `true`.

The manager keeps no per-request state and is safe for long-running workers; redirects are raised as
[`UrlNormalizerRedirectException`](/docs/api/yii/web/urlnormalizerredirectexception/index.md) and handled by the application.

See also: [`LanguageChangedEvent`](/docs/extensions/localeurls/reference/languagechangedevent/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-baseUrl"></span>[`$baseUrl`](/docs/api/yii/web/urlmanager/index.md#property-baseUrl) | `string` | The base URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-cache"></span>[`$cache`](/docs/api/yii/web/urlmanager/index.md#property-cache) | [`yii\caching\CacheInterface`](/docs/api/yii/caching/cacheinterface/index.md)`\|array\|string\|bool\|null` | The cache object or the application component ID of the cache object. Default: `'cache'`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`$defaultLanguage`](#property-defaultLanguage) | `string\|null` | Default language: the language of URLs without a code when [`$enableDefaultLanguageUrlCode`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enableDefaultLanguageUrlCode) is `false`. Default: `null`. | `UrlLanguageManager` |
| [`$enableDefaultLanguageUrlCode`](#property-enableDefaultLanguageUrlCode) | `bool` | Whether the default language uses a URL code like any other language. Default: `false`. | `UrlLanguageManager` |
| [`$enableLanguageDetection`](#property-enableLanguageDetection) | `bool` | Whether to detect the language from the `Accept-Language` header when the URL has no code and no language is persisted. Default: `true`. | `UrlLanguageManager` |
| [`$enableLanguagePersistence`](#property-enableLanguagePersistence) | `bool` | Whether to persist the language from the URL in the session and the language cookie. Default: `true`. | `UrlLanguageManager` |
| <span id="property-enableLocaleUrls"></span>`$enableLocaleUrls` | `bool` | Whether to enable language processing; when `false`, the manager behaves like [`UrlManager`](/docs/api/yii/web/urlmanager/index.md). Default: `true`. | `UrlLanguageManager` |
| [`$enablePrettyUrl`](#property-enablePrettyUrl) |  | Whether to enable pretty URLs; must be `true` while locale URLs are enabled. Default: `true`. | `UrlLanguageManager` |
| <span id="property-enableStrictParsing"></span>[`$enableStrictParsing`](/docs/api/yii/web/urlmanager/index.md#property-enableStrictParsing) | `bool` | Whether to enable strict parsing. Default: `false`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`$geoIpLanguageCountries`](#property-geoIpLanguageCountries) | `array` | GeoIP country codes indexed by the language they select. Default: `[]`. | `UrlLanguageManager` |
| [`$geoIpServerVar`](#property-geoIpServerVar) | `string` | Name of the server variable that carries the GeoIP country code. Default: `'HTTP_X_GEO_COUNTRY'`. | `UrlLanguageManager` |
| <span id="property-hostInfo"></span>[`$hostInfo`](/docs/api/yii/web/urlmanager/index.md#property-hostInfo) | `string` | The host info (e.g. `https://www.example.com`) that is used by [`createAbsoluteUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createAbsoluteUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`$ignoreLanguageUrlPatterns`](#property-ignoreLanguageUrlPatterns) | `array` | Regular expressions that exclude routes and URLs from language processing. Default: `[]`. | `UrlLanguageManager` |
| [`$keepUppercaseLanguageCode`](#property-keepUppercaseLanguageCode) | `bool` | Whether to keep uppercase letters of language codes in URLs. Default: `false`. | `UrlLanguageManager` |
| [`$languageCookieDuration`](#property-languageCookieDuration) | `int` | Lifetime of the language cookie in seconds; `0` disables the cookie. Default: `2592000`. | `UrlLanguageManager` |
| <span id="property-languageCookieName"></span>`$languageCookieName` | `string` | Name of the language cookie. Default: `'_language'`. | `UrlLanguageManager` |
| [`$languageCookieOptions`](#property-languageCookieOptions) | `array` | Additional [`Cookie`](/docs/api/yii/web/cookie/index.md) properties for the language cookie. Default: `[]`. | `UrlLanguageManager` |
| [`$languageParam`](#property-languageParam) | `string` | Name of the [`createUrl()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-createUrl) parameter that selects the language of the created URL. Default: `'language'`. | `UrlLanguageManager` |
| [`$languageRedirectCode`](#property-languageRedirectCode) | `int` | HTTP status code of language redirects. Default: `302`. | `UrlLanguageManager` |
| <span id="property-languages"></span>`$languages` | `array` | Available languages: codes (`en-US`), wildcards (`es-*`), or URL aliases mapped to codes (`'english' => 'en'`). Default: `[]`. | `UrlLanguageManager` |
| <span id="property-languageSessionKey"></span>`$languageSessionKey` | `string\|bool` | Session key that stores the language; `false` disables session persistence. Default: `'_language'`. | `UrlLanguageManager` |
| <span id="property-normalizer"></span>[`$normalizer`](/docs/api/yii/web/urlmanager/index.md#property-normalizer) | [`yii\web\UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md)`\|array\|string\|false` | The configuration for [`UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md) used by this UrlManager. Default: `false`. Available since 2.0.10. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-routeParam"></span>[`$routeParam`](/docs/api/yii/web/urlmanager/index.md#property-routeParam) | `string` | The GET parameter name for route. Default: `'r'`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-ruleConfig"></span>[`$ruleConfig`](/docs/api/yii/web/urlmanager/index.md#property-ruleConfig) | `array` | The default configuration of URL rules. Default: `['class' => 'yii\web\UrlRule']`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-rules"></span>[`$rules`](/docs/api/yii/web/urlmanager/index.md#property-rules) | `array` | The rules for creating and parsing URLs when [`$enablePrettyUrl`](/docs/api/yii/web/urlmanager/index.md#property-enablePrettyUrl) is `true`. Default: `[]`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-scriptUrl"></span>[`$scriptUrl`](/docs/api/yii/web/urlmanager/index.md#property-scriptUrl) | `string` | The entry script URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-showScriptName"></span>[`$showScriptName`](/docs/api/yii/web/urlmanager/index.md#property-showScriptName) | `bool` | Whether to show entry script name in the constructed URL. Default: `true`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-suffix"></span>[`$suffix`](/docs/api/yii/web/urlmanager/index.md#property-suffix) | `string` | The URL suffix used when [`$enablePrettyUrl`](/docs/api/yii/web/urlmanager/index.md#property-enablePrettyUrl) is `true`. Default: `null`. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="property-_defaultLanguage"></span>`$_defaultLanguage` protected | `string` | Default language resolved by [`init()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-init) from [`$defaultLanguage`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-defaultLanguage) or the application language. Default: `''`. | `UrlLanguageManager` |
| <span id="property-cacheKey"></span>[`$cacheKey`](/docs/api/yii/web/urlmanager/index.md#property-cacheKey) protected | `string` | The cache key for cached rules Default: `__CLASS__`. Available since 2.0.8. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-addRules"></span>[`addRules()`](/docs/api/yii/web/urlmanager/index.md#method-addRules) | Adds additional URL rules. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-createAbsoluteUrl"></span>[`createAbsoluteUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createAbsoluteUrl) | Creates an absolute URL using the given route and query parameters. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`createUrl()`](#method-createUrl) | Creates a URL and inserts the language code after the base URL or the script name. | `UrlLanguageManager` |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBaseUrl"></span>[`getBaseUrl()`](/docs/api/yii/web/urlmanager/index.md#method-getBaseUrl) | Returns the base URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`getDefaultLanguage()`](#method-getDefaultLanguage) | Returns the default language: [`$defaultLanguage`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-defaultLanguage), or the application language captured when the manager was initialized. | `UrlLanguageManager` |
| <span id="method-getHostInfo"></span>[`getHostInfo()`](/docs/api/yii/web/urlmanager/index.md#method-getHostInfo) | Returns the host info that is used by [`createAbsoluteUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createAbsoluteUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-getScriptUrl"></span>[`getScriptUrl()`](/docs/api/yii/web/urlmanager/index.md#method-getScriptUrl) | Returns the entry script URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`init()`](#method-init) | Captures the default language and validates the configuration. | `UrlLanguageManager` |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`parseRequest()`](#method-parseRequest) | Resolves the request language, removes its code from the path info, and parses the request. | `UrlLanguageManager` |
| <span id="method-setBaseUrl"></span>[`setBaseUrl()`](/docs/api/yii/web/urlmanager/index.md#method-setBaseUrl) | Sets the base URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-setHostInfo"></span>[`setHostInfo()`](/docs/api/yii/web/urlmanager/index.md#method-setHostInfo) | Sets the host info that is used by [`createAbsoluteUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createAbsoluteUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-setScriptUrl"></span>[`setScriptUrl()`](/docs/api/yii/web/urlmanager/index.md#method-setScriptUrl) | Sets the entry script URL that is used by [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) to prepend to created URLs. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-buildRules"></span>[`buildRules()`](/docs/api/yii/web/urlmanager/index.md#method-buildRules) protected | Builds URL rule objects from the given rule declarations. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-canBeCached"></span>[`canBeCached()`](/docs/api/yii/web/urlmanager/index.md#method-canBeCached) protected | Returns the value indicating whether result of [`createUrl()`](/docs/api/yii/web/urlmanager/index.md#method-createUrl) of rule should be cached in internal cache. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`detectLanguage()`](#method-detectLanguage) protected | Detects the language from the `Accept-Language` header, then from the GeoIP country. | `UrlLanguageManager` |
| <span id="method-getBuiltRulesFromCache"></span>[`getBuiltRulesFromCache()`](/docs/api/yii/web/urlmanager/index.md#method-getBuiltRulesFromCache) protected | Provides the built URL rules that are associated with the $ruleDeclarations from cache. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-getUrlFromCache"></span>[`getUrlFromCache()`](/docs/api/yii/web/urlmanager/index.md#method-getUrlFromCache) protected | Get URL from internal cache if exists. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| [`loadPersistedLanguage()`](#method-loadPersistedLanguage) protected | Returns the language persisted in the session or, failing that, in the language cookie. | `UrlLanguageManager` |
| [`matchCode()`](#method-matchCode) protected | Matches a language code against [`$languages`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languages), case-insensitively and including wildcards. | `UrlLanguageManager` |
| [`persistLanguage()`](#method-persistLanguage) protected | Stores the language in the session and the language cookie. | `UrlLanguageManager` |
| [`processLocaleUrl()`](#method-processLocaleUrl) protected | Resolves the language of the request and returns the language redirect it requires. | `UrlLanguageManager` |
| <span id="method-setBuiltRulesCache"></span>[`setBuiltRulesCache()`](/docs/api/yii/web/urlmanager/index.md#method-setBuiltRulesCache) protected | Stores $builtRules to cache, using $rulesDeclaration as a part of cache key. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |
| <span id="method-setRuleToCache"></span>[`setRuleToCache()`](/docs/api/yii/web/urlmanager/index.md#method-setRuleToCache) protected | Store rule (e.g. [`UrlRule`](/docs/api/yii/web/urlrule/index.md)) to internal cache. | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md) |

## Events

| Event | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="event-EVENT_LANGUAGE_CHANGED"></span>`EVENT_LANGUAGE_CHANGED` | [`LanguageChangedEvent`](/docs/extensions/localeurls/reference/languagechangedevent/index.md) | Raised before a language from the URL that differs from the persisted one is persisted. Event name: `'languageChanged'`. | `UrlLanguageManager` |

## Property details

### $defaultLanguage <span id="property-defaultLanguage"></span>

```php
public string|null $defaultLanguage = null
```

Default language: the language of URLs without a code when [`$enableDefaultLanguageUrlCode`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enableDefaultLanguageUrlCode) is `false`.

`null` captures `Yii::$app->language` in [`init()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-init). Set it explicitly in long-running workers, where the
application object and its language persist between requests; it is also applied to `Yii::$app->language` at the
start of each request.

### $enableDefaultLanguageUrlCode <span id="property-enableDefaultLanguageUrlCode"></span>

```php
public bool $enableDefaultLanguageUrlCode = false
```

Whether the default language uses a URL code like any other language.

When `false`, a URL without a code uses the default language, and a URL with the default code redirects to the
URL without it (default `fr`: `/fr/some/page` -> `/some/page`), which also resets the persisted language. When
`true`, a URL without a code redirects to the default code (`/some/page` -> `/fr/some/page`).

### $enableLanguageDetection <span id="property-enableLanguageDetection"></span>

```php
public bool $enableLanguageDetection = true
```

Whether to detect the language from the `Accept-Language` header when the URL has no code and no language is
persisted.

GeoIP detection through [`$geoIpLanguageCountries`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-geoIpLanguageCountries) applies regardless of this setting.

### $enableLanguagePersistence <span id="property-enableLanguagePersistence"></span>

```php
public bool $enableLanguagePersistence = true
```

Whether to persist the language from the URL in the session and the language cookie.

When `true`, a URL without a code redirects to the persisted language (`/some/page` -> `/fr/some/page`).

### $enablePrettyUrl <span id="property-enablePrettyUrl"></span>

```php
public $enablePrettyUrl = true
```

Whether to enable pretty URLs; must be `true` while locale URLs are enabled.

Declared without a native type to match [`UrlManager::$enablePrettyUrl`](/docs/api/yii/web/urlmanager/index.md#property-enablePrettyUrl).

### $geoIpLanguageCountries <span id="property-geoIpLanguageCountries"></span>

```php
public array $geoIpLanguageCountries = []
```

GeoIP country codes indexed by the language they select.

```php
[
    'de' => ['DEU', 'AUT'],
    'ru' => ['RUS', 'BLR', 'KAZ'],
]
```

### $geoIpServerVar <span id="property-geoIpServerVar"></span>

```php
public string $geoIpServerVar = 'HTTP_X_GEO_COUNTRY'
```

Name of the server variable that carries the GeoIP country code.

Names starting with `HTTP_` are read as the request header they represent (`HTTP_X_GEO_COUNTRY` ->
`X-Geo-Country`); other names are read from `getServerParams()` when the request provides it, otherwise from
`$_SERVER`.

### $ignoreLanguageUrlPatterns <span id="property-ignoreLanguageUrlPatterns"></span>

```php
public array $ignoreLanguageUrlPatterns = []
```

Regular expressions that exclude routes and URLs from language processing.

Keys match routes in [`createUrl()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-createUrl), which then adds no language code; values match the path info in
[`parseRequest()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-parseRequest), which then resolves no language.

The first pair assumes URL rules that map `login` and `register` to `site/login` and `site/register`.

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

### $keepUppercaseLanguageCode <span id="property-keepUppercaseLanguageCode"></span>

```php
public bool $keepUppercaseLanguageCode = false
```

Whether to keep uppercase letters of language codes in URLs.

When `false`, created URLs use lowercase codes, and a URL with an uppercase country (`/de-AT/page`) or with an
alias spelled differently from its configuration (`/AT/page`) redirects to the lowercase URL.

### $languageCookieDuration <span id="property-languageCookieDuration"></span>

```php
public int $languageCookieDuration = 2592000
```

Lifetime of the language cookie in seconds; `0` disables the cookie.

Applies only when [`$enableLanguagePersistence`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enableLanguagePersistence) is `true`.

### $languageCookieOptions <span id="property-languageCookieOptions"></span>

```php
public array $languageCookieOptions = []
```

Additional [`Cookie`](/docs/api/yii/web/cookie/index.md) properties for the language cookie.

`httpOnly` defaults to `true`; `name`, `value`, and `expire` always come from [`$languageCookieName`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languageCookieName), the
language, and [`$languageCookieDuration`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languageCookieDuration).

### $languageParam <span id="property-languageParam"></span>

```php
public string $languageParam = 'language'
```

Name of the [`createUrl()`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#method-createUrl) parameter that selects the language of the created URL.

URLs created with this parameter switch to that language; without it, the current application language is used.

### $languageRedirectCode <span id="property-languageRedirectCode"></span>

```php
public int $languageRedirectCode = 302
```

HTTP status code of language redirects.

Redirects caused only by the URL normalizer keep the normalizer status code.

## Method details

### createUrl() <span id="method-createUrl"></span>

```php
public function createUrl(array|string $params): string
```

Creates a URL and inserts the language code after the base URL or the script name.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$params` | `array\|string` | Route and parameters; [`$languageParam`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languageParam) selects the language of the URL. |

**Returns**

`string`: Created URL.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if the base URL or the script URL cannot be determined.

### getDefaultLanguage() <span id="method-getDefaultLanguage"></span>

```php
public function getDefaultLanguage(): string
```

Returns the default language: [`$defaultLanguage`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-defaultLanguage), or the application language captured when the manager was
initialized.

**Returns**

`string`: Default language code, for example `en`.

### init() <span id="method-init"></span>

```php
public function init(): void
```

Captures the default language and validates the configuration.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if locale URLs are enabled while [`$enablePrettyUrl`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enablePrettyUrl) is `false`, or if the parent configuration is invalid.

### parseRequest() <span id="method-parseRequest"></span>

```php
public function parseRequest(yii\web\Request $request): array|bool
```

Resolves the request language, removes its code from the path info, and parses the request.

Each request object is processed once; later calls only parse it. A request not processed yet first resets
`Yii::$app->language` to [`$defaultLanguage`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-defaultLanguage) when it is set. When the request must move to its canonical
language URL, [`UrlNormalizerRedirectException`](/docs/api/yii/web/urlnormalizerredirectexception/index.md) carries the target URL and [`$languageRedirectCode`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languageRedirectCode), or
the normalizer status code when only the URL normalizer requires the redirect. A redirect raised by a URL rule
with a string URL is rethrown unchanged.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) | Request to parse. |

**Returns**

`array|bool`: Route and parameters, or `false` if no rule matches the request.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if the path info of the request cannot be determined.
- [`yii\web\NotFoundHttpException`](/docs/api/yii/web/notfoundhttpexception/index.md): if no rule matches the request while a language redirect is pending, or if the URL normalizer action is `ACTION_NOT_FOUND` and the path info is not normalized.
- [`yii\web\UrlNormalizerRedirectException`](/docs/api/yii/web/urlnormalizerredirectexception/index.md): if the request must be redirected.

### detectLanguage() <span id="method-detectLanguage"></span>

```php
protected function detectLanguage(yii\web\Request $request): string|null
```

Detects the language from the `Accept-Language` header, then from the GeoIP country.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) | Request that provides the header and the GeoIP country. |

**Returns**

`string|null`: Detected language code, or `null` if no configured language matches.

### loadPersistedLanguage() <span id="method-loadPersistedLanguage"></span>

```php
protected function loadPersistedLanguage(yii\web\Request $request): string|null
```

Returns the language persisted in the session or, failing that, in the language cookie.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) | Request that provides the language cookie. |

**Returns**

`string|null`: Persisted language code, or `null` if none is stored.

### matchCode() <span id="method-matchCode"></span>

```php
protected function matchCode(string $code): array
```

Matches a language code against [`$languages`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-languages), case-insensitively and including wildcards.

Exact matches skip wildcards and return the configured spelling. A wildcard match (`es-*`) returns the configured
spelling of the language and the first subtag when it is a 2-3 letter region, in uppercase: `ES-mx-variant` ->
`['es', 'MX']`; any other subtag is dropped: `es-Latn` -> `['es', null]`. A code whose region is not configured
falls back to its language when that language is configured: `de-CH` -> `['de', null]`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$code` | `string` | Language code to match, for example `en`, `en-US`, or `es-MX`. |

**Returns**

`array`: Matched language and country, or `[null, null]` if no configured language matches.

### persistLanguage() <span id="method-persistLanguage"></span>

```php
protected function persistLanguage(yii\web\Request $request, string $language): void
```

Stores the language in the session and the language cookie.

Triggers [`EVENT_LANGUAGE_CHANGED`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#event-EVENT_LANGUAGE_CHANGED) first when handlers are attached and the language differs from the
persisted one.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) | Request that provides the previously persisted language. |
| `$language` | `string` | Language code to persist, for example `en` or `de-AT`. |

### processLocaleUrl() <span id="method-processLocaleUrl"></span>

```php
protected function processLocaleUrl(yii\web\Request $request): string|null
```

Resolves the language of the request and returns the language redirect it requires.

A language code at the start of the path info is removed from it, applied to `Yii::$app->language`, and
persisted. Without a code, the persisted language, then the detected language, then (with
[`$enableDefaultLanguageUrlCode`](/docs/extensions/localeurls/reference/urllanguagemanager/index.md#property-enableDefaultLanguageUrlCode)) the default language selects the redirect target.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) | Request whose path info is processed. |

**Returns**

`string|null`: Language code or alias to redirect to, `''` to redirect to the URL without a language code, or `null` if no language redirect is required.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if the path info of the request cannot be determined.