Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

I18n Workflow

i18n scheme

I18n Context

I18n will generate a I18nContextInterface object at every request which is accessible via the resolver service I18nContextResolverInterface. Which means, that you're able to fetch the I18nContextInterface via [DI] $contextResolver->getContext($request) wherever a valid frontend-request is available!

Locale Definition

The I18n Context contains a LocaleDefinitionInterface object, which contains all locale information about the requested locale.

Route Item

The I18n Context contains a RouteItemInterface object, which terminates the right route process.

  • If the i18n context gets resolved via request, the route item will be generated depending on the request attributes (static route, symfony route, document)
  • If the i18n context gets resolved by a headless context generation or a simple url(route_name, {}), the route item will be generated depending on the route parameters (static route, symfony route, document)


The I18n Context contains a ZoneInterface object, which holds all active zone information (allowed/active locales, bounded domains)

Zone Site

Each ZoneInterface object is able to contain one or more ZoneSiteInterface objects. Each Site contains dedicated information and also provides an SiteRequestContext object. The site request context holds some important information (like host, port) which are required when it comes to absolute URL generation!


I18n will decorate the router service. This is required to provide a simple way generating URLs in different contexts (twig, API, command line). The I18nRouter automatically takes care about the correct router context. If you need absolute URLs for example, just set UrlGeneratorInterface::ABSOLUTE_URL and you're good to go.

PIMCORE Link Generator

Every Link Generator needs to implement the I18nLinkGeneratorInterface! This is required to allow i18n to generate translatable static routes by itself!


namespace App\Service;

use I18nBundle\LinkGenerator\I18nLinkGeneratorInterface;
use I18nBundle\Model\RouteItem\LinkGeneratorRouteItemInterface;
use Pimcore\Model\DataObject\ClassDefinition\LinkGeneratorInterface;
use Pimcore\Model\DataObject\Concrete;

class ObjectLinkGenerator implements LinkGeneratorInterface, I18nLinkGeneratorInterface
    public function getStaticRouteName(Concrete $object): string
        return 'test_route';

    public function generateRouteItem(Concrete $object, LinkGeneratorRouteItemInterface $linkGeneratorRouteItem): LinkGeneratorRouteItemInterface
        $linkGeneratorRouteItem->getRouteParametersBag()->set('object_id', $object->getId());

        return $linkGeneratorRouteItem;

    public function generate(Concrete $object, array $params = []): string
        // do not use this method if you're using i18n.
        // use generateForI18n() instead!

        return '';

Static Routes

PIMCORE static routes are in yaml format now and this allows us to determinate the static route patterns via container parameters:

        - key: 'myStaticRouteKey'
              de: 'meine-statische-route'
              en: 'my-static-route'
                name: my_static_route
                pattern: '/([a-zA-Z0-9-_]*)\/(?:%i18n.route.translations.myStaticRouteKey%)\/(.*?)$/' ## returns (meine-statische-route|my-static-route)
                reverse: '/{%%_locale}/@myStaticRouteKey/%%object_id'
                controller: App\Controller\DefaultController::staticRouteAction
                variables: '_locale,object_id'
                defaults: null
                siteId: null
                methods: null
                priority: 1
                creationDate: 1634472684
                modificationDate: 1634472684

Symfony Routes

I18n also supports (localized) symfony routes. You need to pass the _i18n default flag (can be an array or just a boolean flag).

Localized Symfony Routes

        de: /de/i18n/symfony-default-rut
        fr: /fr/i18n/symfony-default-ruteee
        de_CH: /de-ch/i18n/symfony-default-route-guetzli
        en: /en/i18n/symfony-default-route
        _i18n: true
        _controller: App\Controller\DefaultController::symfonyRouteAction

I18n Localized Symfony Routes

Every I18n translation key is available as a regex parameter (i18n.route.translations.TRANSLATION_KEY_NAME). This allows you to define translations at a global scope and is much cleaner to configure

        - key: 'mySymfonyRouteKey'
              de: 'meine-symfony-route'
              en: 'my-symfony-route'
    path: /{_locale}/i18n/{matching_route_key}
                matching_route_key: mySymfonyRouteKey
        _controller: App\Controller\DefaultController::symfonyRouteAction
        matching_route_key: '(%i18n.route.translations.mySymfonyRouteKey%)' ## returns (meine-symfony-route|my-symfony-route)

Twig|PHP Route Generation

Command Line Route Generation

Generating absolute URLs in CLI is easy!

Non-I18n Routes

I18n always requires the _i18n parameter node in urlGenerator->generate. If this node is not present, the default route generation will be triggered.

dump($router->generate('my_non_i18n_aware_symfony_route', ['_locale' => 'en'], UrlGeneratorInterface::ABSOLUTE_URL));


I18n allows you to easily fetch the current context via a given request object. Read more about it here.

Custom Context Boot

Generating a complete headless context object via twig or php api. Read more about it here.

Code Examples

Please check out the code examples doc section to learn more about accessing zone information.