zxI18nRoutingPlugin
1.0.0stable
for sf 1.2 MIT
The zxI18nRoutingPlugin extends sfPatternRouting class giving possibility to translate routes patterns static text 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.
Developers
License
Copyright (c) 2009 Zbigniew Niedzielski
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
zxI18nRoutingPlugin
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 ;).
Content
zxPatternI18nRouting class which extends sfPatternRoutingapp:zx-routes task which is extended version of app:routes to show plugin specific generated routesapp:zx-routes-duplicates task which looks for duplicated routes (with the same pattern), useful for sites with many routes
Installation
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)
all:
routing:
class: zxPatternI18NRouting
param:
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.
Configuration
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
Setup:
- 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.
Tests
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.
Changelog
2009-08-25 | 1.0.0 Stable
Zbigniew "ZAAN" Niedzielski 