[icu-support] ICU Accept Language API Proposal (Java)

Date: 20 May 2005
Expires: 27 May 2005

Jitterbug #4360  [   http://bugs.icu-project.org/cgibin/icu-bugs? 
findid=4360  ]

First, the explanation (copied from Oct 8's email):

(Originally sent: 8 ta' Ottubru 2004 18:35:52 GMT-07:00)

------------------------
Motivation / Background:

These APIs provide a function to negotiate the best locale to use for  
an operation, given a user's list of acceptable locales, and the  
application's list of available locales.

One of the intended uses of this API is with the HTTP Accept- 
Language: field, see:
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4

Here is another article which describes some of the cautions about  
using accept-language:
  http://www.w3.org/International/questions/qa-accept-lang-locales

------------------------
Theory of operation:

Two input lists are passed to the function:

1. The "Accept List" is from the user/client preference, for example,  
from the HTTP request header.  It is ordered in decreasing order of  
preference.
2. The "Available List" is from the application, for example, from  
the list of installed locales. It is not ordered.


  In the best-case situation, the earliest (preferred) locale from  
the Accept list is matched to an exact match in the available list.  
In this situation, a 'Valid' locale is returned.

  Before failing completely, the ICU API will attempt a fallback from  
the Accept list.   Note that this differs from the HTTP  
specification, and is noted appropriately in the return values of the  
API as a 'Fallback'.

  To illustrate the fallback behavior, consider the following examples.
An input accept list of "de_LX, ja"  behaves like "de_LX, ja, (de)",  
with "de" being fallback behavior, only if the other two locales were  
not found. Similarly, an input accept list of "de_LX_FOO, de_CH_BAR,  
ja_JP" behaves like "de_LX_FOO, de_CH_BAR, ja_JP, (de_LX, de_CH, de,  
ja)".  The Fallback locales are considered in descending order of  
length, following the requested locales.
   The HTTP specification says that de_LX should not match de. As  
well, HTTP spec says that 'de' in the accept-list should match  
'de_LX'. However, we assume that application and ICU locale bundles  
are well-formed, so that if there is a 'de_LX' there will be 'de' and  
we will match it.  Therefore, we will not match an accept-locale of  
'de' to an available locale of 'de_LX'.


Now, the C API as in jitterbug

  Two versions of the API are provided for C and Java.  One is passed  
the Accept-Language field from HTTP (as a single string), and the  
other an array of Locales.  Note that the numeric weights of the  
Accept-Language are only used to order the accept list items, their  
values are otherwise unimportant.

====== ====== ====== ====== ====== ====== ====== ====== ======
JAVA
----



static ULocale acceptLanguage(String acceptLanguageList, ULocale[]
availableLocales, boolean[] fallback);

static ULocale acceptLanguage(ULocale[] acceptLanguageList, ULocale[]
availableLocales, boolean[] fallback);

NullPointerException is thrown if acceptLanguageList or  
availableLocales is
null.  If fallback is non-null, it will contain true if a fallback  
locale (one
not in the acceptLanguageList) was returned.  The value on entry is  
ignored.
ULocale will be one of the locales in availableLocales, or the ROOT  
ULocale if
if a ROOT locale was used as a fallback (because nothing else in
availableLocales matched).  No ULocale array element should be null;  
behavior
is undefined if this is the case.


The following two use ULocale.getAvailableLocales implicitly.

static ULocale acceptLanguage(String acceptLanguageList, boolean[]  
fallback);
static ULocale acceptLanguage(ULocale[] acceptLanguageList, boolean[]
fallback);




C API as in ICU 3.2, for reference:
     Jitterbug #3591  [   http://www.jtcsv.com/cgibin/icu-bugs/others? 
id=3591  ]


/**
* enums for the 'outResult' parameter return value
* @see uloc_acceptLanguageFromHTTP
* @see uloc_acceptLanguage
* @draft ICU 3.2
*/
typedef enum {
   ULOC_ACCEPT_FAILED   = 0,  /* No exact match was found. */
   ULOC_ACCEPT_VALID    = 1,  /* An exact match was found. */
   ULOC_ACCEPT_FALLBACK = 2   /* A fallback was found, for example,
                                 Accept list contained 'ja_JP'
                                 which matched available locale 'ja'. */
} UAcceptResult;


/**
* @param httpAcceptLanguage - "Accept-Language:" header as per HTTP.
* @param result - buffer to accept the result locale
* @param resultAvailable the size of the result buffer.
* @param availableLocales - list of available locales to match
* @param status Error status, may be BUFFER_OVERFLOW_ERROR
* @return length needed for the locale.
* @draft ICU 3.2
*/
U_DRAFT int32_t U_EXPORT2
uloc_acceptLanguageFromHTTP(char *result, int32_t resultAvailable,
                             UAcceptResult *outResult,
                             const char *httpAcceptLanguage,
                             UEnumeration* availableLocales,
                             UErrorCode *status);

/**
* @param acceptList -list of acceptable languages
* @param acceptListCount - count of acceptList items
* @param result - buffer to accept the result locale
* @param resultAvailable the size of the result buffer.
* @param availableLocales - list of available locales to match
* @param status Error status, may be BUFFER_OVERFLOW_ERROR
* @return length needed for the locale.
* @draft ICU 3.2
*/
U_DRAFT int32_t U_EXPORT2
uloc_acceptLanguage(char *result, int32_t resultAvailable,
                     UAcceptResult *outResult, const char **acceptList,
                     int32_t acceptListCount,
                     UEnumeration* availableLocales,
                     UErrorCode *status);



Java:




-------------------------------------------------------
This SF.Net email is sponsored by Oracle Space Sweepstakes
Want to be the first software developer in space?
Enter now for the Oracle Space Sweepstakes!
http://ads.osdn.com/?ad_id=7412&alloc_id=16344&op=click
_______________________________________________
icu-support mailing list - [email protected]
To Un/Subscribe: https://lists.sourceforge.net/lists/listinfo/icu-support