zxI18nRoutingPlugin - 1.0.0

Application routing with I18n for SEO purposes

You are currently browsing
the website for symfony 1

Visit the Symfony2 website

« Back to the Plugins Home


Forgot your password?
Create an account



advanced search
Information Readme Releases Changelog Contribute
Show source


The zxI18nRoutingPlugin extends sfPatternRouting class giving possibility to translate routes patterns static text parts to different languages.

Plugin uses i18n functionality to translate route patterns. E.g. /group/view becames /gruppe/sicht for de culture and /grupa/widok in pl. It has very good effect on indexing pages by search engines (SEO) for multilingual sites.

One of the main goal of creating this plugin was to introduce these feature without any time consuming modifications in existing projects. It doesn't need any changes in existing routes. Plugin installation limits to factories.yml modification and creating XLIFF translation files for chosen languages. Thanks to it you will be able to translate other plugins default patterns language to what you need without plugins routes modification.

Plugin is unit and functional tested and works with each kind of routes and routes collections (see SVN for it). Maybe it would be included in core symfony ;).


  • zxPatternI18nRouting class which extends sfPatternRouting
  • app:zx-routes task which is extended version of app:routes to show plugin specific generated routes
  • app:zx-routes-duplicates task which looks for duplicated routes (with the same pattern), useful for sites with many routes


  • Install the plugin

    $ symfony plugin:install zxI18nRoutingPlugin
  • Change routing class in factories.yml from sfPatternRouting to zxPatternI18nRouting and add two new params use_cultures (default array()) and culture_into_url (default false)

      class: zxPatternI18NRouting
       generate_shortest_url:            true
       extra_parameters_as_query_string: true
       use_cultures:                     [pl, de]   # destination cultures. Plugin looks for translations for these cultures.
       culture_into_url:                 false      # defines if culture should be always placed in url 
  • Create XLIFF files named routing.pl.xml, routing.de.xml (depends what you need) and place it in i18n directory of your app. (e.g. /apps/frontend/i18n)

  • Turn on sf_i18n in settings.yml

  • Clear the cache

    $ symfony cache:clear

How plugin works

For each route defined in application and other plugins, zxI18nroutingPlugin automatically creates additional routes for chosen cultures if translation is possible and stores them in cache. Then if you use url_for based functions the translated route is automatically chosen. When visitor clicks such link, page opens in desired language (sf_culture is set).

Example: baseing on above installation settings. You define group_view_route with /group/view pattern. Plugin automatically creates two routes more with patterns /grupa/widok for pl and /gruppe/sicht for de. Right now wherever you use group_view_route it changes depending on current user culture. When culture is de, then link is /gruppe/sicht. When culture is pl, then link is /grupa/widok. For any other languages it is default pattern /group/view.


If plugin is run with default params it behaves exactly as sfPatternRouting.

There are two configuration parameters which you can change:

  • use_cultures - is an array of cultures of your site, plugin looks for translation files for these cultures. If translation is not possible, default pattern is used.

  • culture_into_url - if set to true, the :sf_culture parameter is placed on the beginning of each automatically created route (except for patterns which already contains :sf_culture).

Example 1: culture_into_url is true and use_cultures is [pl, de]

You define group_view_route with /group/view pattern. Plugin automatically creates three routes more with patterns /pl/grupa/widok for pl and /de/gruppe/sicht for de and /:sf_culture/group/view for other languages.

Example 2: culture_into_url is true and use_cultures is []

You define group_view_route with /group/view pattern. Plugin automatically creates one route more with pattern /:sf_culture/group/view. If you set sf_culture for route group_view_route, then that additional pattern will be used.

IMPORTANT! When culture_into_url is false check out if translation for different languages gives different patterns, because only one of them will be working.

Example: if translation of /test/route in pl and de gives /testy/routed for both, a page would open with pl or de (depends on cultures order in use_cultures array). Use app:zx-routes-duplicates to find conflicts

Case studies


  • We defined in factories.yml use_cultures as [en, de, pl, fr]
  • We got only translation files for de and pl placed in i18n folder
  • Route xz_test_route is /group/view
  • Current culture is pl
  • Default user culture is en

Examples of use:

  • link_to('','xz_test_route') gives:

    • /grupa/widok (case 1 when cultures_into_url is false)
    • /pl/grupa/widok (case 2 when cultures_into_url is true)
    • both open page with culture pl
  • link_to('','xz_test_route',array('sf_culture'=>'pl')) the same as first example

  • link_to('','xz_test_route',array('sf_culture'=>'de')) gives:

    • /gruppe/sicht (case 1)
    • /de/gruppe/sicht (case 2)
    • both open page with culture de
  • link_to('','xz_test_route', array('sf_culture' => sfConfig::get('sf_default_culture')) gives:

    • /group/view (case 1 - note that this link will not change user current culture to default)
    • /en/group/view (case 2 - note that such route will always change user culture to default)
    • first one opens page with current culture or with default culture if browser session starts, second one opens always with default culture
  • link_to('','xz_test_route',array('sf_culture'=>'fr')) gives:

    • /group/view (case 1)
    • /fr/group/view (case 2)
    • the same comment as for above example for default culture.
  • link_to('','xz_test_route',array('sf_culture'=>'se')) gives:

    • /group/view (case 1)
    • /se/group/view (case 2)
    • the same comment as for examples for default culture and fr.


If you want to run unit and functional tests, take it from SVN. Change the path to symfony libs directory in dirs.php, which is placed in /test/bootstrap.


2009-08-25 | 1.0.0 Stable

  • zaan: Initial release