Internationalization Support

Encoding Requirements

The character encoding in the APIs is UTF-8 for both requests and responses. Invalid input will be rejected. In the query parameter of a URI, characters that are not from the ASCII subset allowed in URIs must be hex-encoded based on their UTF-8 bytes. When transmitting text through HTTP headers, all strings containing characters that are not allowed directly in headers must be encoded as MIME-encoded words.

Language Support

The Yahoo! Social APIs support languages in addition to the default, which is United States English (en-US). To specify a language, you can either append the lang query parameter to the URI or specify the Accept-Language header of the HTTP request. If you specify the language in both places, the lang query parameter has precedence. The language tag must conform to RFC 4646. Examples language tags: zh-Hans (Simplified Chinese), en-GB (British English), and zh-Hant-HK (Traditional Chinese as used in Hong Kong).

For example, if the end users of an application speak Canadian French, to retrieve the profile of user 1234, an application calls the HTTP GET operation on the following URI:

http://social.yahooapis.com/v1/user/1234/profile?lang=fr-CA

In the Accept-Language header, you can specify multiple language tags in a comma-separated list, in descending priority. For example, if "de-DE,fr-CA,en-US" is your priority list, the API responds with the first language that it has available.

In the response, the language tag is in the Content-Language header and in the body. If the response format is XML, in the body, the language tag is the value of the xml:lang attribute of the root resource element. If the response is JSON, the language tag in the body is the value of the object named lang.

To find out if a language is supported for a resource, perform the following test: Call the HEAD operation on the resource, specifying the language, and then check the language tag in the response header.

Language Dependencies in Requests and Responses

As you write your applications, you should be aware of the following three types of language dependencies:

  • Content transmitted in the form typed in by end users.

    This content is available only in the original language, often without language identification. Examples: The user names, locations, and declared interests in the user profile of the Social Directory API. Your applications must use this content as-is.

  • Content transmitted in language-independent formats.

    This content includes RFC 4646 language tags, RFC 3339 time values, and enumerations. Examples: The languages spoken and relationship status in the user profile of the Social Directory API; the "updated" time stamp in most Web service responses. Your applications should render such values as localized strings or formats. For example, if an enumeration value is "MARRIED", for de-DE the localized string is "verheiratet" and for en-US it is "married". (The de-DE language tag indicates the German language as spoken in Germany. The en-US code indicates the English language in the USA.) If the RFC 3339 time value is "2008-07-30T21:30:00Z", for example, for de-DE the localized format is "30.07.08, 23:30 MESZ" and for en-US it is "7/30/08 2:30pm PDT". When submitting this type of content, your applications might need to convert user input into the language-independent format.

  • Content provided in language-dependent form.

    This content has been localized according to the language tag your application specifies in the lang query parameter or Accept-Language request header. Examples: The localized event description strings in the Updates API; the sort order of nicknames in the Connections API.

Country Identification

An application can identify a country or dependent territory by specifying the region query parameter. The value of region must be an ISO 3166-1 alpha-2 country code. Examples of this code: DE (Germany), CN (China), HK (Hong Kong), PR (Puerto Rico), US (United States).

A Yahoo! Web service might use region to identify the following:

  • The country-specific Web site that the user has accessed.
  • The jurisdiction whose rules the Web service applies when deciding which content to block from a user. The jurisdiction might be derived from the site that the user accesses or from the Terms of Service (TOS) that the user has agreed to.
  • The country or countries in which the user is interested so the Web service can provide content accordingly. For example, a Web service providing movie information would include the MPAA rating for US users, but the FSK rating for German users.
  • The country where the user lives. This might be used to provide information and advertising that is local to the user's residence, such as news or sports. It might also be used to derive defaults for user preferences such as the measurement system and currency.
  • The country where the user is currently located. This might be used to provide information and advertising that depends on the location, such as weather forecasts, train schedules, or entertainment listings.

To find out if a Web service supports the region parameter, check the Query Parameters Supported section in the chapters that follow. If a Web service supports region, the response body includes the yahoo:region attribute (XML) or the region object (JSON).

Note that the Work and School objects of the Social Directory API also identify the country of a user.

Table of Contents