= !MapGuide RFC 45 - Enhanced Locale Support =

This page contains a change request (RFC) for the !MapGuide Open Source project.  
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status == 
 
||RFC Template Version||1.0|| 
||Submission Date||Jan 23, 2008||
||Last Modified||Walt Welton-Lair [[Timestamp]]||
||Authors||Walt Welton-Lair, Trevor Wekel||
||RFC Status||adopted||
||Implementation Status||completed||
||Proposed Milestone||2.0||
||Assigned PSC guide(s)||Tom Fukushima||
||'''Voting History'''||Feb 4, 2008||
||+1||Tom, Bruce, Andy, Paul, Jason, Haris ||
||+0||||
||-0||||
||-1||||
||Abstain||Bob||
 
== Overview ==

!MapGuide currently supports specifying locales using two-letter language codes from the ISO 639-1 standard, e.g. LOCALE=en.  We need to extend this to support locales encoded as [language]-[country], as allowed by the HTTP Accept-Language header (e.g. en-us or en-gb).


== Motivation ==

A two-letter language code is sometimes insufficient to distinguish between the different variations of a language.  Chinese is a good example.  Using just a two-letter language code ("zh" for Chinese) does not allow a localization distinction between the two languages "Simplified Chinese" and "Traditional Chinese".  However using the proposed extended format these would be uniquely encoded as zh-CN and zh-TW.


== Proposed Solution ==

For !MapGuide, the HTTP Accept-Language header is a reasonable way to determine the language:

http://www.w3.org/International/questions/qa-accept-lang-locales.

The value of the header is generally encoded as [language]-[country], such as en-us, en-gb, zh-cn, or zh-tw.  The country can be upper or lower case.  HTTP also accepts just "en" or "zh".

!MapGuide platform code (MgUserInformation::!SetLocale) will be extended to accept both formats.  To simplify the permutations we will convert to a (lower)-(upper) convention, i.e. zh-cn would become zh-CN.  Resource filenames would also follow this convention, e.g. "mapguide_zh-CN.res" or just "mapguide_zh.res".  A browser can make a request using either the extended format or the basic format.  If the extended format is requested and those resources are not found, then we default to the basic format.  In other words, "zh-CN" should default to using "zh" resources if "zh-CN" resources are not present.

The web tier methods !EnumerateApplicationContainers, !EnumerateApplicationWidgets, and !EnumerateApplicationTemplates look for a subfolder that matches the locale code.  They will also need to be updated to try the "parent" codes of the extended codes if they cannot be found (e.g. if "zh-CN" cannot be found, look for "zh").

The session affinity code requires parsing of a session ID, which contains the locale.  This code will be looked at to determine if the use of extended codes requires any modifications.


== Implications ==

There are no backwards compatibility issues: HTTP requests using the basic format will continue to work.

When providing language resource files that use the extended format, a default file that uses the basic format must also be provided.  This can simply be a copy of one of the extended versions.  Both the extended and basic versions must reside in the same folder (the folder specified by the !ResourcesPath setting in serverconfig.ini and webconfig.ini).

Extended format resource files need to use the (lower)-(upper) convention (matters in Linux where filenames are case-sensitive).

The Fusion framework uses the locale passed in by the LOCALE url parameter to determine which string bundles to load – it may require minor modifications to support extended locale codes.  DM Solutions would be required to make the changes, which are most likely trivial.


== Test Plan ==

Update the web tier test pages to make HTTP requests using both the basic and extended formats.


== Funding/Resources ==

Supplied by Autodesk.