ez.no / documentation / ez publish / technical manual / 4.6 / features / multi-language support for...

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Multi-language support for URL aliases

In eZ Publish 3.10, a new feature that makes it possible to use multilingual virtual URLs (also known as nice URLs or URL aliases) was introduced. This feature allows URL aliases to exist in several translation languages.

Auto-generated aliases

From 3.10, the automated virtual URL generation mechanism allows URL aliases to exist in several languages, depending on which languages the actual objects exist in. In other words, the URL aliases for nodes are now created in accordance with the existing translations of the objects encapsulated by the nodes. When a new translation is added to an object, the system will automatically generate a new set of URL aliases (based on the translations) for the node(s) that encapsulate that object.

A new field "URL alias name pattern" has been added to the class edit interface. It controls how the virtual URLs of the nodes will be generated when the objects (instances of the classes) are created.

It is not possible to create, edit or remove auto-generated aliases using the administration interface. They are updated automatically when objects are changed. The only way to change an auto-generated alias is to edit the object itself in the corresponding language.

URL history entries

When the name of an object is changed, the system will take care of changing the auto-generated URL aliases for the associated nodes. In addition, an internal redirection will be created, which will make sure that the old URL still works. In other words, instead of deleting the old URL alias from the database, the system will convert it into a URL history entry. The old virtual URL will continue to redirect until a new node is created that uses the same URL. In this case, the old virtual URL will be deleted.

Note that the internal redirection mechanism is intentionally hidden from the user. You cannot view or manage URL history entries using the administration interface.


Let's say that a folder called "Computers" contains an article called "Monitors", which can be accessed at "http://www.example.com/Computers/Monitors". If you rename the folder to "Hardware", the new URLs for accessing the folder and the article will be "http://www.example.com/Hardware" and "http://www.example.com/Hardware/Monitors". If someone tries to use one of the old URLs, the system will automatically redirect the user to the corresponding new URL. If you then rename the article into "LCD", the following three URLs will redirect the user to "http://www.example.com/Hardware/LCD":

  •  http://www.example.com/Computers/Monitors
  •  http://www.example.com/Computers/LCD
  •  http://www.example.com/Hardware/Monitors

Manual/user-defined aliases

The following two types of virtual URLs can be managed using the administration interface:

  •  Global URL aliases
  •  Node URL aliases

The list of global URL aliases contains all user-defined virtual URLs, except from those that are created for destinations (system URLs) like "content/view/full/node_id", where "node_id" is the ID number of a node. These are called node URL aliases and can be managed separately for individual nodes.

While global aliases always start from the root of the site, an alias of a node can either start from the parent node or from the root of the site. This is controlled by the "Relative to parent" flag.

A node URL alias applies only to the specific node that it references; in other words, a user-defined alias of a node does not apply to the URLs for the node's children. Refer to the example below for more information.


Let's say that a folder called "Norway" contains two articles that can be accessed using the following URLs:

  •  http://www.example.com/norway/oslo
  •  http://www.example.com/norway/bergen

and you have created a new URL alias "Kingdom" for this folder. In this case, the "Norway" folder will be accessible through any of the following URLs:

  •  http://www.example.com/norway
  •  http://www.example.com/kingdom

However, the following two URLs will bring up a "Module not found" error:

  •  http://www.example.com/kingdom/oslo
  •  http://www.example.com/kingdom/bergen

Redirection of URL aliases and wildcards

In 4.0.0, it is possible to choose whether an alias will work as a "direct" or "forward" one ("direct" == the entered URL in the address bar of a browser stays the same, "forward" == the system will redirect to the original URL), but only for URL wildcards. This is controlled by the "Redirecting URL" checkbox when creating URL wildcards.

URL aliases also gained a new feature. You have now the possibility to choose if a URL alias should be direct or re-direct . Previously aliases have always re-directed (HTTP 301). Versions prior to 3.10 did not redirect URLs pointing to modules. With this new feature this behavior is back.

Find an example of redirection of URL aliases in the screenshot below:

Use the "Alias should redirect to its destination " check-box to redirect the alias.

Wildcard based URL forwarding

eZ Publish supports wildcard based URL forwarding. This means that you can create a URL alias that contains one or more asterisks (*) and the system will automatically replace the corresponding parts in URLs according to the destination URL specified. For example, you can create a URL alias called "pictures/*/*" and specify "media/images/{1}/{2}" as a destination. In this case, a URL like "http://www.example.com/pictures/home/photo/" will load "http://www.example.com/media/images/home/photo/". In other words, you will be able to use "pictures" instead of "media/images" in the URLs when accessing content nodes that are located two or more levels beneath the "media/images" node.

 It is possible to choose whether an alias will work as a "direct" or "forward" one. In the example above, a "direct" alias means that when someone enters "http://www.example.com/pictures/home/photo/" in the address bar of a browser, the entered address will stay the same while the actual node will be displayed. If the alias is of the "forward" type, the system will redirect to "http://www.example.com/media/images/home/photo/" instead.

Wildcard URL aliases can be managed using the administration interface.


An alias is only available for a siteaccess if the language of the alias matches one of the site languages specified for this siteaccess. If a siteaccess is configured to display untranslated content, then aliases in all languages will be available.

If an object is always available, the URL aliases for the object's node assignments will be available for all siteaccesses. This is true for both auto-generated and user-defined aliases.

Aliases which are always available

Some global aliases always need to be available regardless of which languages that are configured for a siteaccess. Because of this, a new flag called "Include in other languages" has been introduced for global aliases. It makes it possible to individually control the availability of the different aliases.


Multilingual URL aliases do not control which languages the requested pages will be displayed in. When a virtual URL of a node is requested, the system will figure out the correct language based on the language configuration of the current siteaccess (refer to the example below).


If you create an article called "Company" and translate it into French, there will be two auto-generated URL aliases called "Company" and "Compagnie".

Let's say that you have two public siteaccesses called "gb" and "fr" with the following language configuration:

Siteaccess "gb"

Siteaccess "fr"


As the table shows, the "gb" siteaccess is configured to use English as the most prioritized language and French as a second one. This means that both "Company" and "Compagnie" aliases will work. The system will bring up the English version of the article when one of the following URLs is requested:

  •  http://www.example.com/gb/Company
  •  http://www.example.com/gb/Compagnie

Note that if you configure only one language (English) for this siteaccess, the French alias will not be available.

While the most prioritized language for the "fr" siteaccess is French, the second one is English. This means that both aliases will work and the corresponding URLs will bring up the French version:

  •  http://www.example.com/fr/Company
  •  http://www.example.com/fr/Compagnie

Character transformation

The multilingual URL aliases feature includes 3 recommended character transformation options for URLs, out-of-the-box. Their usage is controlled by the "TransformationGroup" directive located in the [URLTranslator] section of an override for "site.ini". The following table reveals the recommended transformation options.




This method supports lowercase Latin letters from "a" to "z", digits and underscores in URLs. It provides the same behavior as in eZ Publish 3.9.x and earlier versions. Capital characters are not preserved.


This method supports more characters, but the URLs are still restricted to the ASCII table (with a few exceptions). Capital characters are preserved.


This method allows all Unicode characters in the URLs (with a few exceptions). It preserves the original text as much as possible, which results in more user-friendly URLs. Multiple whitespaces are converted to one. Capital characters are preserved. This is the recommended method for both single- and multi-language sites.

 If you use the "urlalias_iri" type of transformation for URL aliases, be aware of the fact that some web browsers use percent encoding for Unicode characters in the URLs. For example, if a visitor enters a URL like "http://www.example.no/Ostehøvel" in the address bar of a browser, it might be automatically converted to "http://www.example.no/Osteh%C3%B8vel". However, this won't prevent eZ Publish from serving the requested web page. Users of Mozilla Firefox can disable this behavior by typing about:config in the browser's address bar to edit the "network.standard-url.escape-utf8" preference.

Refer to the following example to learn how the multilingual URL alias feature actually works.


Let's say that we have the following site structure:

  •  Company (node ID: 10)
    •  About us (node ID: 11)
    •  Contacts (node ID: 12)

If node 10 ("Company") gets translated into French, it will get the second alias "Compagnie". The structure of the site will look like this:

  •  Company|Compagnie (node ID: 10)
    •  About us (node ID: 11)
    •  Contacts (node ID: 12)

At this point, node 10 can be accessed by using both aliases for all siteaccesses that have both English and French on the list of site languages. If a siteaccess is configured to use English as the most prioritized language, both aliases will bring up the English version. If the most prioritized language is French, both aliases will bring up the French version of the company page for this siteaccess.

The "About" page (node 11) can be accessed using either "Company/About" or "Compagnie/About" as the URL. The "Company/About" alias will work for any siteaccess that has English on the list of site languages. The "Compagnie/About" alias will only work for the siteaccesses that are configured to use both English and French languages. In both cases, it is the English translation that will be displayed (since the object only exists in English). If you edit the "About" page and enable the "Always available" flag, the page will be accessible through both aliases for all siteaccesses regardless of their language configuration (even if a siteaccess does not have English on the list of site languages).

If the "Contacts" page (node 12) is translated into German, it will get the second alias "Kontakten". In this case, the structure of the site will look like this:

  •  Company|Compagnie (node - id 10)
    •  About us (node - id 11)
    •  Contacts|Kontakten (node - id 12)

At this point, it will be possible to access the page "Contacts|Kontakten" (node 12) by using one of the four URL aliases listed below. The following table shows which language configuration of a siteaccess is required for each alias to work.

URL alias

Site languages that must be enabled




English and French


English and German


French and German

Julia Shymova (14/09/2010 12:21 pm)

Ricardo Correia (26/07/2013 11:12 am)

Geir Arne Waaler, Ricardo Correia


  • Firefox URLs are not understood by eZ publish

    From section on "Character Transformation":

    "For example, if a visitor enters a URL like "http://www.example.no/Ostehøvel" in the address bar of a browser, it might be automatically converted to "http://www.example.no/Osteh%C3%B8vel". However, this won't prevent eZ Publish from serving the requested web page."

    In my experience this is not correct. The URL "Kunnskapsbank/EØS" gives "Module Kunnskapsbank not found" after Mozilla turns it into "Kunnskapsbank/E%D8S", which eZ publish apparently cannot parse. I have just upgraded to 3.10.0 and have run the
    • Re: Firefox URLs are not understood by eZ publish


      Tested here with Firefox, and this seems to work correctly, Kunnskapsbank/EØS is transformed into Kunnskapsbank/E%C3%98S in the address bar. Which char set is your website in? Make sure your website uses utf-8 ( search this in the html source: <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> ) and your database as well.
  • Multilingual website - english & greek

    I want to make multilingual website in both english and greek, kindly help me out with some useful resources.. i am a newbie....