This document lists a set of localization scenarios and describes how Firefox OS handles these different use cases. The document makes some recommendations about how particular use cases could be better addressed.
To simplify the discussion, this document assumes the runtime is running in locale "en-US".
Use case: The author does not wish to explicitly localize any content.
{
"name": "foo"
}FxOS: When there is no localized content declared, the user agent just uses what is at the root of the manifest. Hence, the name of the app is "foo".
Use case: The author provides the required name member, but chooses to localize the application's name for the "en-US" locale. However, the author neglects to add the default_locale member.
{
"name": "unknown-locale name",
"locales": {
"jp": {
"name": "jp name"
},
"en-US": {
"name": "en-US name"
}
}
}FxOS: Despite there not being any default_locale, the user agent still chooses "en-US name" as the name for the application. When neither localized content matches, the value at the root of the manifest is selected.
Use case: The author declares the name of the application using a set of variants of the English language. The author omits the default_locale member.
{
"name": "unknown-locale name",
"locales": {
"en-US-x-test": {
"name": "en-US-x-test name"
}
"en-US": {
"name": "en-US name"
},
"en": {
"name": "en name"
}
}
}FxOS: The user agent selects the localized content that exactly matches the user agent's default language (so, in this case, "en-US name" is shown).
Use case: The author declares the name of the application using a set of variants of the English language. However, none of them match the user agent's locale settings exactly. Fortunately, the author has included a catch all ("en").
{
"name": "unknown-locale name",
"locales": {
"en-AU": {
"name": "en-AU name"
}
"en-GB": {
"name": "en-GB name"
},
"en": {
"name": "en name"
}
}
}FxOS: The user agent first checks for "en-US", but failing that, it selects the next best match, which is "en name".
Use case: The author wants to localize the name, but does not need to localize the developer information.
{
"name": "unknown-locale name",
"developer": {
"name": "unknown-locale author"
},
"locales": {
"en-US": {
"name": "en-US name"
},
"jp":{
"name": "jp name"
}
}
}FxOS: The user agent selects "en-US" as the name, and "unknown-locale author" as the author.
Use case: the author wants to localize the developer name but not the developer URL.
{
"name": "unknown-locale name",
"developer": {
"name": "unknown-locale author",
"url": "http://unknown-locale.com/"
},
"locales": {
"en-US": {
"developer": {
"name": "localized author"
}
}
}
}FxOS: The user agent selects the localized developer name and uses the unknown-locale developer url.
Use case: When the author uses any value for default_locale, but no localized content is given through a locale member, the author still expects some content to be displayed to the user (even if they user might not be able to understand it).
{
"name": "unknown-locale name",
"developer": {
"name": "unknown-locale author"
},
"default_locale": "unknown-locale"
}FxOS: The user agent selects "unknown-locale name" as the name of the application.
Use case:
{
"name": "unknown-locale name",
"developer": {
"name": "unknown-locale author"
},
"locales": {
"en-US": {
"name": "en name"
},
"en": {
"developer": {
"name": "en developer"
}
}
},
"default_locale": "unknown-locale"
}The name of the app is "en name".
FxOS: When neither the default_locale nor the user agent locale matches any localized content, FxOS just uses the first sub-tag of the language range (in this case, just "en"). So, "en-US" becomes "en" (see code).
BUG 846269: Because FxOS currently takes the first subtag in a language range, this will exclude language ranges initially composed of three or more subtags (e.g., zh-Hans-XQ). This means that if the user's regional preference is expressed as "zh-Hans-XQ", the following will not match any localized content (when zh-Hans would have been a reasonable match):
{
"name": "unknown-locale name",
"developer": {"name": "unknown-locale author"},
"locales": {
"zh-Hans": {
"name": "zh-Hans name"
}
},
"default_locale": "unknown-locale"
}Use case: The author wishes for the name of the application to be localized for a particular locale. However, the author does not want to duplicate the developer information.
{
"name": "您好！颜色",
"locales": {
"en-US": {
"name": "Hi! Color"
},
"en-AU": {
"name": "G'Day! Colour"
},
"en": {
"developer": {
"name": "en developer"
}
}
},
"developer": {
"name": "中国开发者"
},
"default_locale": "zh-Hans"
}FxOS: The user agent selects "Hi! Color" as the name, but then selects "中国开发者" as the developer. Expected "name": "en developer" to be selected. Filed BUG 846432.
Proposal: To address the above, the user agent should arrange the user's preferred locales and decompose them in order (removing any duplicates). So, if the user has "en-US, en-AU, jp" as her preferred language settings, those would decompose to "en-US, en-AU, en, jp".