Language mapping in TYPO3 with RealURL and bootstrap package

The cool thing about the TYPO3 bootstrap_package extension is that you can set up a new site within minutes because everything is pre-configured. This also includes the RealURL setup so you already see the page titles in your URLs and the language parameter value is mapped too.

The dark side

You will face the dark side of the bootstrap package when you try to use different languages than those configured as examples. There's only a mapping between the value of sys_language_id and English, German and Danish available and if you try to add a mapping manually, RealURL immediately switches to the "manual mode" where you have to configure everything yourself once again.

Loosing the auto-configuration implies a lot of work, especially if you are using the Aimeos web shop extension or similar ones, which add a lot of RealURL rules out of the box. Thus, it's very compelling to try to overwrite only the RealURL configuration which is responsible for the language ID/code mapping.

The bright side

Fortunately, the bootstrap package allows you to overwrite its RealURL auto-configuration rules including the preVars section which is responsible for the language mapping.

First of all, you need an extension for your project where you can add the RealURL rules to. You can either use the Kickstarter extension or the Aimeos extension creator. The automatic configuration requires a PHP class and method that will add new or overwrite existing RealURL rules. You should add it in the Classes/Realurl.php file of your extension. Copy this code to your new file:

<?php

namespace <vendor>\<extname>;

class Realurl
{
    public function addAutoConfig( array $params, $pObj )
    {
        $params['config']['preVars'][1] = array(
            'GETvar' => 'L',
            'valueMap' => array(
                'en' => '0',
                'de' => '1',
                '...' => '2',
            ),
            'noMatch' => 'bypass',
        );

        return $params['config'];
    }
}

The addAutoConfig() method replaces the second entry of the "preVars" array, which are exactly the language mapping rules in the bootstrap package. You can change or add as many entries in the "valueMap" array as you like. The array keys are the strings that will be shown in the URL while the values are the sys_language_id values of the languages you've configured in your TYPO3 page tree and TypoScript configuration.

Note: Remember to replace the <vendor> and <extname> placeholders in the namespace statement in the third line of the file. <vendor> can be an arbitrary string while <extname> must be your extension name which the first letter in upper case as well as all letters that follow an underscore, e.g. "bootstrap_package" becomes "BootstrapPackage".

Afterwards, you have to add your class to the RealURL hook that will call your method when collecting the rules for auto-configuration. This is done in the ext_localconf.php of your extension by adding these lines:

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/realurl/class.tx_realurl_autoconfgen.php']['extensionConfiguration']['<extname>'] =
    'EXT:<extname>/Classes/Realurl.php:<vendor>\\<extname>\\Realurl->addAutoConfig';

As above, you have to replace the <vendor> and <extname> placeholders with the same values you've used for the namespace statement.

Warning: The order you will install the extensions matters! Make sure the RealURL extension is installed first, then the bootstrap package and afterwards the rest of the extensions which contain RealURL rules including your new one.

Finally, clear your caches (TYPO3 general and frontend caches) and delete the typo3conf/realurl_autoconf.php file. Then, your languages should appear correctly mapped in your URLs.

Build your multi-language TYPO3 shop

The Aimeos TYPO3 extension turns your TYPO3 site into a full-featured web shop – with SEO-friendly, multi-language URLs out of the box.

Aimeos for TYPO3 View on GitHub