Phrame 3 Documentation

How To Use Language Negotiation

Phrame supports language negotiation much similar to Apache's content negotiation mechanism. The advantage of language negotiation is that you can have separate, localized web pages for each of the languages supported by your application.

Without language negotiation you would have to handle localization in each web page itself, for example using message resources. The latter is often done in applications using Java Server Pages, but there are also other techniques you can use. However, using such techniques in PHP could have serious impact on the performance of your application.

Implementing language negotiation comes with a price: your maintenance effort will increase since you have to maintain multiple localized versions of your web resources. If your application includes many web pages and has to support many languages, implementing the language negotiation mechanism will not be a good idea.

How does it work?

If you have activated language negotiation, the action server will always try to find a localized version of a web resource first when processing the forwards in your module configurations, or forwarding to a configured error page. (See the next paragraph on how to localize a resource.)

To find a localised resource, the server uses the URL specified in the forward / error page configuration and the user's prefered language stated in the request (the accept language), or if a request doesnot refer to a prefered language, the default language configured in the server configuration (_DEFAULT_LOCALE configuration parameter).

As a result one of the following situations may occur:

The action server did find a localized version of the resource and will forward to this resource;
The action server did not find a localized version of the resource, but it did find a resource with the URL specified in the forward. Again, it will forward to this resource;
The action server did not find any resource with the URL specified and will return an error page.

Localizing a web resource

To localize a web resource, include a language code as the last part of the resource file name, just before the file extension. For example: myPage_en.php denotes a resource localized for the English language ('en').

Note that the language code has to be prefixed by an underscore and must be supported by the HTTP standard. Phrame will only use two-character language codes, which could be only part of the code included in a request (i.e. the first two characters).

If you omit the language code, Phrame assumes the resource can be used for any language supported by your application (unless there are localized versions of the resource matching a user's prefered language). It makes sense that the lanuguage used in the web resource in this case is the default language for your action server.

Activating language negotiation (pre 3.1 versions)

The language negotiation mechanism is activated by setting the USE_LANGUAGE_NEGOTIATION parameter in the action server configuration to TRUE. If you set this parameter to FALSE the action server will not look for localized versions of resources to forward to.

Activating language negotiation (version 3.1 and later)

The language negotiation mechanism is activated by setting the USE_LANGUAGE_NEGOTIATION parameter in the Phrame container configuration to TRUE. If you set this parameter to FALSE the action server running in the container will not look for localized versions of resources.