lochmueller / language-detection
Modern language detection middleware for TYPO3. Based on PSR-7, PSR-14 & PSR-15.
Package info
github.com/lochmueller/language_detection
Type:typo3-cms-extension
pkg:composer/lochmueller/language-detection
Requires
- php: ^8.3
- ext-intl: *
- typo3/cms-core: ^13.4 || ^14.3
Requires (Dev)
- ext-json: *
- deptrac/deptrac: ^4.7
- friendsofphp/php-cs-fixer: ^3.95
- geoip2/geoip2: ^3.4
- infection/infection: ^0.31
- phpstan/extension-installer: ^1.2
- phpstan/phpstan: ^2.3
- typo3/cms-frontend: ^13.4 || ^14.3
- typo3/testing-framework: ^9.7
Suggests
- geoip2/geoip2: Allows to use local MaxMind IP database or webservice
Provides
None
Conflicts
None
Replaces
None
README
Meta:
Compatibility:
Quality:
Support:
Table of Contents
Why?
Language Detection should be easy & simple to integrate and powerfully in development! TYPO3 Core do not handle language detection via client information. EXT:languag_detection use a PSR-15/PSR-7 middleware/request (TYPO3 Documentation) to handle a language detection logic via PSR-14 events(TYPO3 Documentation). Very flexible! Give it a try and checkout the future of language detection!
Installation
composer require lochmueller/language-detection
Configuration
Use the site configuration module to configure the language detection. Just enable it, and it will work :) There are several configuration options for the Site configuration that handle the control events. The following screenshot show the options of the detection configuration.
Global configuration
All options of the site configuration are also available in the extension configuration (Admin Tools > Settings > Extension Configuration > language_detection). They are used as fallback for every site, so shared values like the MaxMind credentials do not have to be repeated in every site YAML file.
An option of a site configuration always wins over the global value. An empty field in the site configuration counts as "not set", because the site configuration module writes empty fields to the YAML file. If a site should not use the global configuration at all, enable "Ignore the global extension configuration" (ignoreGlobalLanguageDetectionConfiguration) in the site configuration.
Detection without a matching site
If a request does not match any site, TYPO3 resolves a NullSite and the PageResolver answers with a 404. This happens for example, if every site has a country prefix in the base (https://www.example.com/de/, https://www.example.com/ch/, ...) and there is no site with the root base https://www.example.com/.
The extension can handle this case and redirect to the best matching language of all other sites. The feature is disabled by default and is configured in the extension configuration only:
| Option | Description |
|---|---|
enableNullSiteDetection |
Enable the detection for requests without a matching site |
nullSiteLimitToRequestHost |
Only use languages of sites that are configured for the host of the current request (enabled by default, disable it for cross domain redirects) |
nullSiteAllowedSites |
Comma separated list of site identifiers that are allowed as redirect target (empty means all sites) |
nullSiteFallbackSite |
Site identifier that is used, if no language matches (empty means no fallback, so the regular 404 handling of TYPO3 is used) |
nullSiteFallbackLanguageId |
Language ID of the fallback site |
The user languages are checked in their quality order. Every user language is matched in two steps against all sites, because an exact locale match (e.g. de_CH) of any site is better than a language code match (e.g. de) of the first site. All other checks of the detection still apply, so bots and paths other than / are not redirected (unless allowAllPaths is enabled).
Event Structure
There are four central PSR-14 events that control the language detection. The attached list explain the different events and the default listener. The events are ordered in the execution order.
CheckLanguageDetectionEvent
Check if the language detection should execute by the extension. You can register listeners for this event and call "disableLanguageDetection" on the event object to disable the language detection.
Default-Listener:
| Name | Description |
|---|---|
| BackendUserCheck | Check if a backend user call the language detection and disable the redirect (respect "disableRedirectWithBackendSession" config) |
| BotAgentCheck | Check if a bot call the language detection and disable the redirect |
| EnableCheck | Check if the Language Detection is enabled in the current Site |
| FromCurrentPageCheck | Check the referrer and disable the redirect if the user comes from the current site |
| NullSiteCheck | Check if the request matches no site and disable the redirect (respect "enableNullSiteDetection" extension configuration) |
| PathCheck | Check if the user call "/" and disable the redirect for other paths (respect "allowAllPaths" configuration) |
| WorkspacePreviewCheck | Check if the page is a workspace preview and disable the redirect |
DetectUserLanguagesEvent
This event collect user information to get the user languages. You can register your own detections and manipulate the data via "getUserLanguages" and "setUserLanguages".
Default-Listener:
| Name | Description |
|---|---|
| BrowserLanguageDetect | Get the users "accept-language" languages |
| GeoPluginDetect | Send the IP to ip-api.com and add the language of the location to the checked languages (respect "addIpLocationToBrowserLanguage" configuration) |
| MaxMindDetect | Use MaxMind database or webservice to get the country information |
Please keep data privacy in mind in case of the "IpLanguage" Listener!
NegotiateSiteLanguageEvent
This event calculates the best matching page language for the user. If you build your own listener. Please use "setSelectedLanguage" on the event. If a language is already selected the default listener will be skipped.
Default-Listener:
| Name | Description |
|---|---|
| NullSiteNegotiation | Check the languages of all sites, if the request matches no site |
| DefaultNegotiation | Check the Locale and TwoLetterIso of the TYPO3 languages against the user languages of the previous event |
| FallbackNegotiation | Handle a fallback, if there are no matches by the default negotiation |
| NullSiteFallbackNegotiation | Handle a fallback to a configured site, if the request matches no site and no language matches |
BuildResponseEvent
The last event build the middleware response. You can overwrite this step. You have to use "setResponse" to set the response.
Default-Listener:
| Name | Description |
|---|---|
| DefaultResponse | Build the response object and respect the "redirectHttpStatusCode" config |
Troubleshooting
There are missing or wrong languages in the detection process. Why?
Do you check in incognito mode? The browser will not send all languages in incognito mode. So "wrong results" are possible. Please check the request header to TYPO3 in detail. Otherwise, perhaps the DefaultNegotiation do not handle the "best fitting language" selection process for your needs?
Why the redirect not work on subpages?
The middleware is early in the middleware stack. There is no concept of links and translations (or even page UID). Furthermore, it is recommended not redirect on subpages. A user that call a subpage first bookmark the page or search in a search engine. In both cases the user already get the right language. I suggest hreflang tags so search engines get the right language of the content https://developers.google.com/search/docs/advanced/crawling/localized-versions
Dev
The extension supports TYPO3 13.4 and 14.3 on PHP 8.3 - 8.5. Install the dev dependencies first:
composer install
Run all code standards (PHP CS Fixer, PHPStan and deptrac):
composer code:all
Execute the unit tests:
composer test:unit
With a HTML coverage report:
.Build/bin/phpunit -c phpunit.xml --testdox --coverage-html=var/phpunit
Run the mutation tests:
composer test:infection
Check the extension against another TYPO3 version:
composer require "typo3/cms-core:^13.4" "typo3/cms-frontend:^13.4" --update-with-all-dependencies
Contribution
Thanks all for the great contribution to the project!
Licence
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.