MultiLink

Additional documentation for MultiLink

What's it for?

MultiLink is designed for multi-language sites. Please read the project page for a general description and example use cases. In short, it greatly simplifies management of in-content links to other content (nodes), especially for a site where not all content is available in all languages. Additionally, MultiLink can automatically redirect users to the correct language version of content when, for example, they follow a link elsewhere which would take them to content in a language other than their preferred language.

Path aliases

In many examples below, we refer to paths such as node/100 for simplicity, but in practice urls generated will always use the alias for that node, if defined.

Input Filter

MultiLink provides an input filter which allows you to create a link by entering something like [100: more information] which will be converted to: more information... or a similar link to node/101 if that is the French version of node/100 and the user is browsing French content, or node/102 if that is the Spanish version and the user is browsing Spanish content, and so on. The title of the link (shown by the browser when hovering over the link) will be taken from the actual title of the target node.

Instead of [100: more information] you can use use [100: $] and the link generated will then show the title of the target node.
Advanced users change the format used to enter links in MultiLink's configuration page, e.g. {100|Title} or ::100/Title:: would be possible.

Support for other input filters

MultiLink supports integration with other modules and methods of linking and including nodes in content. In effect it adds "multi-language link" functionality to:

PathFilter
Pathologic
InsertNode
Linodef
link node
Markdown
simple HTML links (anchor tags)

To use these features, you will need to enable them on the configuration page for your filter format, and suitably configure filter order so that MultiLink processing takes place before other relevant filters such as InsertNode. In the cases of Markdown and HTML links, use relative paths starting /node e.g. /node/1234.

MultiLink Redirect sub-module

If installed, redirects requests to a node to the translated version (if available) which can be useful for people who arrive at your site via links on other sites (or even your own site, if not all links are generated by MultiLink). For example, if a user goes to en/node/123 but their preferred language (from browser or account settings) is French, then they will be redirected to fr/node/124 where node/124 is the French translation of node/123. In general, the user will end up at the same page/url that they would have arrived at if they had clicked a link generated by MultiLink.

MultiLink Redirect provides much of the functionality of Global Redirect but using the same rules and cached data used by the MultiLink Filter to determine which page (node) should be served (the exact behaviour of Global Redirect on a multi-language site is currently undefined - see [#201675].)

A permissions setting bypass multilink redirect allows the redirect to be disabled on a role basis, intended for use by admins and translation staff. A message is displayed showing the redirection that would have been performed, so this feature is useful for testing that the module is operating as anticipated.

Redirection of logged in users

In short, the system tries to redirect the user to the "best" url based on the user's language preference, determined by the user account setting if available, or otherwise by the user's browser configuration for preferred language. The interface language (for menus, system messages, etc) will be chosen to match the user's preferred language, and the content (node) chosen will be in their preferred language if available, otherwise some other "best fit" language.

Examples

These examples assume a default configuration for MultiLink - the default preference order of various languages (from browser, user account, url, etc.) can be changed via a configuration setting.

Let's say that the user's preferred language is Italian, and no path aliases exist:

If the user requests it/node/123 and node 123 is in Italian, they will not be redirected - the page will be served in the normal way.
If the user requests en/node/123 and node 123 is not in Italian then they will be redirected to it/node/124, where node 124 is the Italian translation of node 123.
If the user requests en/node/123 and no Italian translation of node 123 exists, they will be redirected to it/node/125 where node 125 is a translation in some other suitable language (see Behaviour below).
If the user requests en/node/123 and no suitable translation of node 123 exists, they will be redirected to it/node/123.

The examples above refer to paths such as node/123 for simplicity, but in practice the user will always be redirected to the alias for a node, if defined.

Redirection of anonymous users

Behaviour depends on whether Drupal page caching is enabled or not. The page cache is normally only active for anonymous users.

If page caching is switched off (or if for some other reason the requested page is not cacheable) then anonymous users are redirected in the same way as logged-in users. Language preference is, by default, determined by user's browser configuration for preferred language.
If page caching is switched on (and the currenlty requested page is cacheable) then anonymous users are not redirected unless the included MultiLink Redirect Cached module is installed and enabled. With that module enabled, anonymous users are redirected in the same way as logged-in users. Language preference is, by default, determined by user's browser configuration for preferred language.

Combination with Global Redirect

MultiLink Redirect has been tested with Global Redirect also installed and the combination found to operate acceptably. However, you may need to alter "weight" in the system table to obtain the desired results. MultiLink Redirect will redirect requests to a single alias (the alias returned by Drupal's url() function) and so this module alone may be adequate to avoid the SEO issues which Global Redirect is designed to address. However, Global Redirect provides other functionality (e.g. dealing with paths to taxonomy terms) so you may need both modules.

How does MultiLink generate urls?

The same process is used for generating urls whether for use as as link-targets or redirection targets.

Definitions:

First let's try to name some of the possible language choices that we have to deal with:

User's preferred-language. This is the language they will always prefer for the site interface (menus, blocks, etc.) and for content if available. preferred-language is taken from the user's account if available, otherwise from their browser configuration.
url-language - The language specified by the url currently requested. e.g. if they are currently at fr/node/123 then url-language is French (though node/123 is not necessarily in French).
The site default-language.
node-language - The language of the node requested, e.g. for fr/node/123 where node 123 is in English, then node-language is English.
result-language - The language chosen by MultiLink as the "best fit" language for content to be displayed (linked or redirected to). This depends on the availability of node translations and order of language selection. - see below.

New in version 2.5, detection of when the user switches to a different language, for example using the standard Drupal language-switcher block. MultiLink subsequently regards the newly selected language as the user's preferred-language for the current browser session.

Behaviour:

MultiLink generates urls using preferred-language as the language prefix (path or sub-domain as defined by site configuration) so that the user will always see the site interface in their preferred-language.
MultiLink tries to choose the "best fit" for result-language depending on available translations. For sites where all content is always available in all relevant languages, this is easy - result-language will be preferred-language. Otherwise, result-language will be set by choosing an available node translation, using order of preference (see below.)
MultiLink Redirect, if installed will redirect from url-language/content-in-node-language to preferred-language/content-in-result-language. It will also redirect non-node paths, e.g. url-language/user will be redirected to preferred-language/user.

Order of language selection

The default order can be changed (since version 2.5) in settings.php. You can add a line in settings.php to control the order in which possible languages are selected.

D6 branch

e.g: $conf['multilink_language_order'] = array(

'selected',

'preferred',

'current', 'default');

selected is the language most recently actively selected by the user (e.g. via a language switcher block.)
preferred is the user's "preferred" language, either from browser settings or defined in the user account.
current is the current interface language.
default is the site default language.

If multilink_language_order is not defined the default order is: selected, preferred, current, default. Note that the user's preferred-language referred to under Behaviour can be over-ridden here - the first of the languages defined by multilink_language_order will be used preferred-language.

D7 branch

As above except language names are in default order are now: selected, preferred, browser, current, content, url and default.

preferred is the user's "preferred" language from account settings.
browser is the user's "preferred" language from browser settings.
url is the langusage specified by the requested url.
content is the language chosen by Drupal to display content - usually the same as current.

Note: Drupal's choice for current and content languages is in-turn determined by language detection and selection settings at admin/config/regional/language/configure.

Performance and caching

Standard Drupal page caching is supported for anonymous users. [*more detail needed - redirection may prevent a cached page from being served, and anonymous users may see a cached page containing links which do not point to the same nodes as they would in the same page non-cached.]

For logged-in users, or when page-caching is not enabled, there are further caching mechanisms:

The module uses a smart caching scheme to avoid performance degradation. For example, it caches links to translated versions of node/100, but if node/100 or a translation of it is added, edited or deleted then the relevant cache entries are cleared so that the generated links will be updated.

Optionally, and currently D6 only, you can enable additional caching by Drupal which will improve performance considerably for non-cached pages. As with page-caching, outdated links may be shown for 24 hours - for example when a new translation is added it will be used as a link or redirect target until the cache has expired. This is an advanced option and to be effective requires the following:

A patch which makes Drupal 6 filter caching language-aware.
A suitably configured input format such that all other filters are cacheable too (you can check with Filter Check).