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) has been 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.

Example

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":

Manual/user-defined aliases

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

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.

Example

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

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:

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

Availability

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.

Languages

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).

Example

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"

[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=eng-GB
SiteLanguageList[]=fre-FR
[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=fre-FR
SiteLanguageList[]=eng-GB

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:

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:

Character transformation

The multilingual URL aliases feature uses 3 types/methods of character transformation for URLs. Their usage is controlled by the "TransformationGroup" directive located in the [URLTranslator] section of an override for "site.ini". The following table reveals the available transformation methods.

Name

Description

urlalias_compat

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.

urlalias

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

urlalias_iri

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 (most effective for sites that are using the UTF-8 character set).


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.

Example

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

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

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:

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

"Company/Contacts"

English

"Compagnie/Contacts"

English and French

"Company/Kontakten"

English and German

"Compagnie/Kontakten"

French and German

Powered by eZ Publish™ CMS Open Source Web Content Management. Copyright © 1999-2013 eZ Systems AS (except where otherwise noted). All rights reserved.