Page tree
Skip to end of metadata
Go to start of metadata

See Urltranslation for the 5.6 compatible version.

Magnolia Compatibility


What is the Urltrans Module?

Take a look at this page:

If you choose to store your international website in ONE hierarchy you face the problem that the URL cannot be localized. This is very bad for SEO as the URL is very important to search engines.

The urltrans module allows you to localize the URL even if you have only one hierarchy.

How to use it?

The localized property "name" is used to store the localized name of a website document.

The name used for the fallback language is not configured in a property. Here the node name of the website document is used

The page properties tab of the STK dialog is modified (/modules/standard-templating-kit/dialogs/generic/master/basePageProperties/tabMain/name).

Only safe characters are allowed (e.g. no '/'). When you set the localized name for the fallback language the website document will be renamed. This is currently resulting in a 404 error, because you are still editing the old document. 

How does it work?

When the web user requests a localized URL a filter looks up the localized URL by querying the JCR repository. When it finds the document it simply replaces the URL with the the node's path.

Filters which are executed after the UrltransFilter (like ContentSecurity) see the path in fallback language.

Filters which are executed before the UrltransFilter (like CacheFilter) see the localized path. The document is stored in the Magnolia cache at the very end of the filter chain, but the clever cache developers use the request path and not the handle of the aggregationState, so caching works perfectly.

A link transformer renders the URL in the localized language. Unfortunately the following STK class must be changed for versions prior to STK 2.0.11. Without this patch the the URLs of CSS stylesheets are rendered incorrectly.


                // remove the content related part from the full uri
                // now we can create the link safely and we are sure that the multisite filter will
                // detect the correct site
                int ndx = fullLinkToPage.length();
                for (int cnt = StringUtils.countMatches(pagePath, "/"); cnt > 0; cnt--)
                     ndx = fullLinkToPage.lastIndexOf('/', ndx-1);
                linkPrefix = fullLinkToPage.substring(0,  ndx);
                // fullLinkToPage may have been localized 
                // linkPrefix = StringUtils.removeEnd(fullLinkToPage, pagePath);


On the public instances the JCR query result is cached in memory. The cache is cleared during activation.






  1. Now available in git and nexus

  2. Can you provide instruction on how to build the urltrans module. We want to deploy it on 4.5 community edition.

    I tried:

    git clone
    cd urltrans
    mvn package

    You have a dependency on the extended templationg kit? Do you have a binary somewhere?

    1. Yes, there is a dependency on etk. The link manager makes sure that links point to the localized URL.

      Check Nexus for the binary:;quick~urltrans

      Or Hudson:


  3. Hi, please note that nexus now has to be accessed via https.  Http access will be switched off shortly.  I've just updated the link in Sven's comment from September above.

  4. Hi,

    Is the module compatible with Magnolia 5?
    (We currently use it with Magnolia 4.5 and works very well)

  5. No, sorry. Currently 4.5 only. But I hope that one of my customers will migrate to 5.3 soon. Then I will update it.

    1. Hi Roland are there any news of an update of your module to 5.3?

      1. I don't think it will be done before April.

        1. Maybe i can help you to migrate it, because at the moment one of our customers has the exact usecase in Magnolia 5.3

          1. Go ahead and try. Maybe there is not much to do

            1. Version 2 works with Magnolia 5.3.9

              1. Version 3 works with Magnolia 5.4 and without STK

                1. Hi Roland,

                  how to get version 3? On Nexus, I only see a version 1.0.0-SNAPHOT (;quick~urltrans)



                  1. I was never able to create versions that work with nexus and jenkins. I think I got an error message that I have no permissions

                    You have to get the sources from git and compile by yourself:

                    1. Thanks. Above git repo asked for authentication, so I used
                      The module depends on the multisite-module though, but I would need it for the Community Edition. Therefore, I replaced the two LinkTransformer classes and URLtransVersionHandler with the ones from v2 and removed the multisite-module depency in the pom.xml.

                    2. did you tried "mvn deploy"

                      I would love to use the maven repository. Maybe you need to ask again for authentication.

                        1. Check that you use https instead of http for all Nexus URLs in your POM

                          You can also double check it with my module pom.xml;a=blob;f=pom.xml;h=58a95287772dc2089a7ef78be11c7696dfb9f3b2;hb=HEAD

                          It is similar.

                            1. Did you checked your settings.xml that you use the correct username/password. It should be the same like your JIRA/Confluence credentials. Otherwise you need to ask for auth on your nexus repos directy.

                            2. Any news on this authentication problem?

                              1. Finally I got help from Gregory. My groupId was incorrect. Now it works

                                1. Awesome. Thank you very much.


              2. Hello Roland. Thanks for contributing!

                Where can i get the version 2 of the module? Is there a way to put it in my web-apps pom.xml? Is there a built jar that i can drop in my WEB-INF/lib directory?

  6. How to enable the LinkTransformer in Freemarker so that the template engine uses the correct, localized link?

    I got the module working in 5.4.1 CE, and the URIMapping works fine when opening it in a browser, like /en/products.html and /de/produkte.html gets mapped properly after I added name_de = "produkte" node property for example. Note that I added the property via JCR browser directly, since I did not get any dialog for setting this when editing a page.

    But when linked to a page from the German (de) locale, which is of class info.magnolia.ui.form.field.definition.LinkFieldDefinition and put in freemarker like this:


    it would always take the fallback name/link (products.html), regardless under which locale I am currently browsing.Thanks.

    1. Any idea about this? Is it supposed to work out of the box with just the regular directive? Thanks.

      1. If it does not work, please check if this has been executed correctly by the module's version handler:

                tasks.add(new SetPropertyTask(RepositoryConstants.CONFIG, "/server/redering/linkManagement", "class", ""));

                tasks.add(new SetPropertyTask(RepositoryConstants.CONFIG, "/server/redering/linkManagement/transformers/absolute", "class", ""));

        1. There is a typo in the source code: "redering" should be "rendering". I changed it and now it works (smile)

  7. Hi Roland Polzer,

    We have setup the Ultrans module on the Magnolia 5.4 without any issues. The module can be seen inside the Config app.

    The only problem is how to use the module. A page was created with some dummy template assigning it different name_de, name_fr, name_it properties however without success.

    How exactly should the Ultrans module be used in the Pages app ?

    Which is the localized name of the property to be used ?


    Sanel Mesinovic

    1. Hi Sanel Mesinovic , I got it to work with 5.4.1. name_de, name_fr, name_it are the right properties to use. But make sure you fix the two typos in the source code, as I mentioned earlier in above comment. Otherwise the rendering won't take place. (Not sure if it has already been fixed in the original code yet.)

  8. Hi Mathias Conradt,

    Thanks a lot for the explanation. Honestly speaking we would prefer to use it as a Maven dependency instead of cloning it. Don't think it was fixed, otherwise it would be working.

    1. Additional note: because I am using Community Edition instead of Enterprise Edition, I did some additional adjustments, because SiteManagement was references in the sources, but I needed it without it. If you are using Enterprise Edition anyway, it should be fine for you.

      1. Just noticed in the Config app, those two typos seem to be fixed. The exist under the node path with the values specified in the code.

        I am using CE with the magnolia-module-enterprise module enabled. Still does not work. I will check what happens if I switch to the EE bundle.

        1. I made a mistake in git. the master was not up-to-date. I have commited now. The version handler should set /server/rendering/linkManagement/transformers/absolute

          1. Hi Roland Polzer,

            I am not using git, but Maven dependency:






            Does the Nexus contain the latest artifacts with corrected code ?

            Is Ultrans module dependent on the Advanced Cache module ? I get ClearCache event exceptions each time the name_xx property is saved under the page's node.

            Here is what I see in the Config app:

            1. Config looks identical to mine.

      2. Each time I add the new property to the page e.g. name_de, name_fr, name_it the following exception is raised:


        2015-09-28 09:24:01,581 WARN  .jackrabbit.core.observation.ObservationDispatcher: EventConsumer com.eqs.magnolia.urltrans.translator.ClearCacheEvent threw exception

        java.lang.IllegalStateException: Expected an instance of [] for the [info.magnolia.cms.core.AggregationState]





         at com.eqs.magnolia.urltrans.translator.Translator.<init>(

         at com.eqs.magnolia.urltrans.translator.Translator.getInstance(

         at com.eqs.magnolia.urltrans.translator.ClearCacheEvent.onEvent(

         at org.apache.jackrabbit.core.observation.EventConsumer.consumeEvents(



        Where did you put the name_xx properties ? Directly below the page node ?

        1. Yes, directly under the page node, see this example for my contact page:

        2. When you change the properties it must clear the cache. Could you check in SiteProvider.get() what is the class of the aggregationState?

          1. Unfortunately cannot devote more time to this issue, however I think the issue was that my project was based on the empty-webapp and later on the CE bundle. I think that if it would be based on the EE bundle there should be no more SiteProvider errors, because the Site module is already part of the EE bundle.

            The Site application was not there so I guess that is the reason for the above errors. 

          2. The addition of these properties is happening on author right? Why must that cache be cleared there?

            1. It is not the Magnolia cache. The Translator class has an in-memory cache to reduce costly sql queries

  9. Hi guys, are there still people using this module? I'm using that in Magnolia 5.5.7 as I didn't find any other URL Translation module so far. Works well. The problem is that it doesn't work with Magnolia 5.6. New class doesn't have "getNode" method, which was there before, and UrlTranslation module is calling that (in log.trace !). 

    Is there any other module to have translatable urls, or will this module be updated? 



    1. We're also using the Urltrans module. There is no other module that provides the same functionality as far as I'm aware.

    2. Yes, that's correct. I believe it was changed to getJCRNode(). In 5.6 we removed all code that relied on the old Content API. Roland if you could provide me the source code I could help you update the module. Seems popular (big grin)

      1. Hi Richard, unfortunately I don't have time for this and I am not working with Magnolia anymore. The source code is in and I am hoping that someone from the community takes over

        Cheers, Roland

        1. Ah ok, I was looking in the nexus and I did not see any source code there. Thanks for the link. I will try and get this updated next week then.

          1. We're also looking at using URLtrans with 5.6 - please keep us updated.

  10. This module has been moved to Magnolia URL Translation for Magnolia 5.6+.  → 404 Page Not Found (smile)

    1. (areyoukiddingme) ok then, that space must be private. I will probably move this out to official docs then.

      1. Sure:) Can't wait when it'll be updated. Please let me know (smile) And thanks for the effort.

  11. Hey Guys-

    I've released 1.0 of the new modules just now. It's been refactored into 2 modules. I wanted it to be available for community and standard as well as pro.

    I would suggest that you uninstall the old module first. I plan to add some instructions for uninstall over here Urltranslation. Your current page properties will still work in the new module. I just made some changes to some of the transformer class names.

    If you have any problems with it please file a bug under MURLTRANS or if you have any new feature ideas I'd like to hear those as well.


    1. Hi Richard. It's impossible to build project with this module, as it expects some private dependency:

      [ERROR] Failed to execute goal on project adyen-webapp: Could not resolve dependencies for project com.adyen.magnolia:adyen-webapp:war:7.2.1-SNAPSHOT: Failed to collect dependencies at info.magnolia.i18n:magnolia-url-translation:jar:1.0: Failed to read artifact descriptor for info.magnolia.i18n:magnolia-url-translation:jar:1.0: Could not transfer artifact from/to magnolia.enterprise.releases ( Not authorized , ReasonPhrase:Unauthorized. -> [Help 1]

      I created  SUPPORT-8251 - Getting issue details... STATUS  for that. Please help (wink)

      1. Same Problem here, just tried to install it. We have an EE subscription, and other EE packages download fine.

        1. You need additional repositories configuration:


          1. Sorry about that. We are working on a new space for these modules. Soon all the information will be consolidated here:


            1. Ok, thanks, I will wait for the update... for the moment I can't access that page.

          2. huh, I added those to our Nexus as proxies. Now I get:

            Could not find artifact

            It can't seem to access the addons repository. When I look on Magnolia's nexus I can see it, but not in our proxy (sad)