README

A Craft CMS module that automatically redirects visitors from / to their locale-specific home route based on their browser language preferences.

Features

Detects the visitor's preferred language from the Accept-Language header
Matches it against your Craft multi-site locales
Redirects from / to the best-matching locale home URL (e.g. /en, /fr, /de)
Preserves query parameters through the redirect
Configurable locale exclusions and restrictions
Zero configuration required for basic usage

Requirements

PHP 8.2+
Craft CMS 5

Installation

composer require jorisnoo/craft-locale-redirect

Then register the module in your config/app.php:

return [
    'modules' => [
        'locale-redirect' => \Noo\CraftLocaleRedirect\Module::class,
    ],
    'bootstrap' => ['locale-redirect'],
];

How It Works

When a visitor hits your site's root URL (/), the module:

Reads the Accept-Language header from the browser
Fetches all configured Craft site locales and their URLs
Finds the best match between browser preferences and available locales
Issues a 302 redirect to the matched locale's home URL

If no match is found, the visitor is redirected to the primary site's locale prefix (or a configured fallback). Query parameters are preserved through the redirect.

Redirects always stay on the host the request came in on — only the locale path prefix is taken from the site base URLs. In a multi-domain setup, only locales served under the current site's host are considered as redirect targets; when the primary site lives on another host, the fallback uses the current site's prefix instead.

Configuration

The module works out of the box with no configuration. To customize behavior, create a config/locale-redirect.php file in your Craft project:

<?php

return [
    'excludeSites' => [],
    'exclude' => [],
    'only' => [],
    'fallback' => null,
    'crossHostRedirects' => false,
];

Exclude Sites

Prevent the redirect from triggering on specific sites (by handle). Useful when locale-specific sites already have their own prefix and shouldn't redirect further:

'excludeSites' => ['english', 'german'],

Exclude Locales

Prevent specific locales from being redirect targets:

'exclude' => ['de', 'it'],

Restrict to Specific Locales

Only allow redirection to specific locales. Takes precedence over exclude when both are set:

'only' => ['en', 'fr'],

Fallback URL

The URL to redirect to when no browser locale matches. Defaults to the primary site URL:

'fallback' => '/en',

Cross-Host Redirects

By default, redirects stay on the host the request came in on and only use the locale path prefixes from your site base URLs. If your locales live on separate domains instead (e.g. example.de and example.fr), enable cross-host redirects so the module targets the configured site base URLs verbatim, host included:

'crossHostRedirects' => true,

Note that with this enabled, requests arriving on an alias or staging domain are redirected to the sites' registered domains. When two sites share the same two-letter language on different hosts, a visitor already on one of those hosts stays there; otherwise the first-defined site wins.

Branching and Versioning

This package follows Semantic Versioning. Only Craft 5 is supported.

License

The MIT License (MIT). Please see LICENSE for more information.

jorisnoo / craft-locale-redirect

Maintainers

Package info

Statistics

Security