Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document attempts to map out a complete internationalization (i18n) model for the Widgets 1.0: Packaging and Configuration specification, herein referred to as the [P&C spec]. The document makes a number of proposals that when combined form a complete i18n solution for widgets.
This document is not a specification. This document has been prepared to solicit feedback from the W3C's Web Apps and i18n Core Working Groups, as well as from the general public at large. This document does not contain any normative text and has no official relationship whatsoever to the Widgets 1.0 family of specifications.
This document is a work in progress and should be considered an early draft. However, comments are always welcomed; please email public-webapps@w3.org.
Internationalization, or i18n, is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language. Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a "locale"). A localized widget is a widget package that contains content that an author has explicitly localized. Unlocalized content is content included in the widget package that has not been explicitly localized.
There are four preconditions to achieve i18n:
Each of the above four preconditions require technical solutions to be formally specified in the [P&C spec]. Those technical solutions are the subject of various proposals in this document. In other words, the purpose of the document is to tease out the complexities of an i18n model for widgets and to make a number of proposals, which are prefixed with the word PROPOSAL and grouped by a letter and a number (e.g., A1, A2, and B1, B2), that together form a complete i18n solution for widgets.
The combination of each of the proposals can have subtle or significant effect on how the resulting i18n model works; so, the proposals made in this document must be considered carefully. For each group of proposals, the editor's preference is indicated. How the editor's preferred proposals work together as a coherent whole is demonstrated under the section titled Localization Scenarios.
The first precondition to achieve i18n is for the author to use one or more of the means to localize the content of a widget package using the guidelines provided by the [P&C spec]. The [P&C spec] provides two means that authors can use to explicitly localize the content of a widget for the purpose of i18n:
Both forms of localization are described below. Folder-based and element-based localization work in conjunction with each other. Folder-based and element-based localization rely on the user agent to make use of [BCP47]'s lookup algorithm to match the user agent's locale to the appropriate locale folders and/or localized elements in the widget's configuration document.
To localize file-based content, the author places localized content into folders that use a language-tags as their file name (e.g., "en-au"). In the [P&C spec], these folders are referred to as locale folders and must be placed inside a parent folder called "locales" (e.g., "locales/en-au/", "locales/it/", "locales/cn-zh-tw/", etc.). In the [P&C spec], the folder named "locales" is referred to as the container for localized content. Only if an author has placed a locale folder in the container for localized content will the user agent attempt to use its content in the i18n process.
An example of a widget that uses folder-based localization:
widget.wgt config.xml index.html fun.gif locales/en/fun.gif locales/fr/french.htmllocales/fr/fun.gif
The way a user agent behaves when it encounters localized folders is subject to the following proposals.
PROPOSAL A1: To localize files, the author places localized content into folders named using a language tag inside the container for localized content. There is no functional relationship between the sub-folders of a locale folder. The user agent treats any file or folder outside the container for localized content as unlocalized content.
PROPOSAL A2: To localize files,the author places localized content into folders named using a language tag inside the container for localized content. Authors can further facilitate the localization process by grouping files into folder hierarchies made up of matching sub-tags. The user agent treats any file or folder outside the container for localized content as unlocalized content. This is the editor's preference.
For example, all English versions can share the files "shared1.gif, shared2.gif".
widget.wgt
index.html
config.xml
locales/en/shared1.gif
locales/en/shared2.gif
locales/en/a.gif
locales/en-au/a.gif
locales/en-us/a.gif
some/unlocalized.png This works at all sub-levels, so long as the parent sub-tag matches the child sub-tags. So, for example, the "CN" region below can make use of the localized files in the "zh-Hans" folder level, the "zh" folder level, and the unlocalized files at the root of the widget package. The user agent always prioritizes files in sub-folders over files in locale folders closer to the root of the package.
In the example below, assuming the widget's locale is "zh-hans-cn", content in the "zh-Hans-CN" locale folder would have a higher priority than content in the zh-Hans locale folder, which in turn would have a higher priority than content in the zh locale folder. The content in the zh locale folder would have a higher priority than content at the root of the widget package.
widget.wgt
locales/zh-Hans-CN/a.gif
locales/zh-Hans-CN/f.gif
locales/zh-Hans/a.gif
locales/zh-Hans/b.gif
locales/zh/a.gif
locales/zh/b.gif
locales/zh/c.gif
a.gif
b.gif
c.gif
d.gif
f.gif
g.gif
index.html
config.xmlNote that widgets localized at any level (e.g. "locales/zh/") must be fully functional as a localized widget. That is, authors cannot simply put shared files into a language level folder, but must put all files needed into the language level folder for the widget to work (for example, having "a.gif" in both the "/locales/zh-Hans/" folder and "/locales/zh/").
To localize XML elements in the configuration document, an author explicitly marks XML elements as localized by using an xml:lang attribute either explicitly on an element or somewhere in the document's ancestor chain (i.e., by declaring it on the the widget element).
An example of a configuration document that uses element-based localization:
<widget xmlns="http://www.w3.org/ns/widgets">
<!--
preferences for cities (Lisbon and New York)
-->
<preference name="preferredCity"
value="里斯本"
xml:lang="zh-CN"/>
<preference name="homeCity"
value="纽约"
xml:lang="zn-CN"/>
<!-- city names in Portuguese -->
<preference name="preferredCity"
value="Lisboa"
xml:lang="pt"/>
<preference name="homeCity"
value="Nova Iorque"
xml:lang="pt"/>
<!-- cities for unknown locale (English)-->
<preference name="preferredCity"
value="Lisbon"/>
<preference name="homeCity"
value="New York"/>
</widget>The second precondition to achieve i18n is to derive the user agent's locale from the operating environment and have it represented within the user agent. There are numerous ways a user agent may acquire the end-user's language preference. For instance, the end-user may have specified a language preference at install time by selecting a preferred language, or languages from a list, or a list of preferred languages could have been derived from the OS, etc.
For the purpose of the [P&C spec], however, how the user agent's locale is derived is an implementation detail. Regardless of how the user agent derives the end-user's language preference, the end user's language preference must be represented within the user agent as the user agent's locale. The form the representation takes is the subject of the following proposals:
PROPOSAL B1: The user agent's locale is represented as zero, one, or more language-tags in a list. The items in the list are sorted in order of language preference, where the item at the start of the list is the end-user's most preferred language (e.g., "en-us,en,fr,*"). This is the editor's preference and what is currently in the [P&C spec].
Note: According to the 2006 European Commission's on Europeans and Their Languages, 56% of the people surveyed were able to converse in one language other than their native tongue, and of those 56%,11% are able converse in three languages other than their native tongue. This serves as a relevant use case of A1.
PROPOSAL B2: The user agent's locale is represented as a single language-tag (e.g., "en-us"), which may be empty.
On the one hand, proposal B1 is more flexible than proposal B2, because it allows for more targeted internationalization. However, proposal A1 is more complex to process than A2. On the other hand, proposal B2 is easier to process than B1, but is inflexible in that it does not allow the end-user to specify multiple preferred languages.
The third precondition to achieve i18n is to derive the widget's locale by matching the user agent's locale to localized content in the widget package. If no match is made, the widget is treated as unlocalized, in which case the user agent will only select unlocalized content and present it to the end-user. The widget's locale serves both as an identifier and a filter that the user agent relies on to select the appropriate localized, or unlocalized, content from a widget package.
A number of significant questions need to be addressed in order to derive the widget's locale:
Attempting to provide workable solutions to the questions above is the subject of the proposals of the following sub-sections.
How the user agent derives the widget's locale is the subject of the following three proposals. The proposals rely on [BCP47]'s lookup algorithm, which is used to match the user agent's locale to localized content in the widget (if any) and, at the same time, to derive the widget's locale. Consider the following example widget when considering the proposals.
widget.wgt config.xml index.html fun.gif locales/en/fun.gif locales/en-au/fun.gif locales/fr/french.htmllocales/fr/fun.gif
config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name>nombre</name>
<description>escrito en español</description>
<name xml:lang="en">name</name>
<icon src="a.gif"/>
<content xml:lang="en" src="index.html"/>
</widget>PROPOSAL C1: If there is a locale folder that, upon applying lookup, matches the user agent's locale, then that matching folder's name becomes the widget's locale (e.g., user agent's locale is "en-us", matching folder is "/locales/en/", widget's locale is "en"). If no localized folder is present that matches the user agent's locale, then the elements of the configuration document are searched, using lookup in document order, for an xml:lang attribute that matches the user agent's locale as closely as possible. If a match is made, then the value of the matching xml:lang becomes the widget's locale (e.g., UA locale is "en-us", matching xml:lang value is "en", widget's locale is "en"). If no match is made in either search, then the widget will only use unlocalized content from the root of the widget package. This is the editor's preference, only because it provides consistency in display language and it prioritizes (folder) content over (config) metadata.
PROPOSAL C2: (the reverse of C1, prioritizes configuration document metadata over content localized in folders). Search the configuration document in document order. If, upon applying lookup, an element matches the user agent's locale, then the value of that matching element's xml:lang attribute becomes the widget's locale. If no match is made from searching the configuration document for localized content that matches the user agent's locale, and if there is a locale folder that, upon applying lookup, matches the user agent's locale, then that matching folder's name becomes the widget's locale. If no match is made in both searches, then the widget will only use unlocalized content from the root of the widget package.
PROPOSAL C3: This proposal differs from the above two in that it allows for two different locales: one specifically for folder-based localization, and the other specifically for element-based localization. If there is a locale folder that, upon applying lookup, matches the user agent's locale, then that matching folder's name becomes the widget's folder locale for the purpose of folder-based localization (e.g., user agent's locale is "en-us", matching folder is "/locales/en/", widget's folder locale is "en"). If no match is made, then the widget will only use unlocalized content from the root of the widget package. Now, search the configuration document in document order. If, upon applying lookup, an element matches the user agent's locale, then the value of that matching element's xml:lang attribute becomes the widget's configuration document locale. If a match is made, then the value of the matching xml:lang becomes the widget's locale (e.g., UA locale is "fr-ca", matching xml:lang value is "fr", widget's locale is "fr"). If no match is made, then the widget will only use unlocalized content from the configuration document.
As already stated in C3, the configuration document and the config file are treated as having independent locales. So, for example, consider the file structure of the widget below and the following configuration document. Assume the user agent's locale is "pt" so that no languages match and thus the unlocalized content would be used for folder-based localization:
widget.wgt
config.xml
index.html
foo.gif
locales/jp/foo.gifconfig.xml <widget xmlns="http://www.w3.org/ns/widgets"> <!-- preferences for cities (Lisbon and New York) --> <!-- city names in Portuguese --> <preference name="preferredCity" value="Lisboa" xml:lang="pt"/> <preference name="homeCity" value="Nova Iorque" xml:lang="pt"/> <!-- cities for unknown locale (English)--> <preference name="preferredCity" value="Lisbon"/> <preference name="homeCity" value="New York"/> </widget>
In the case of the configuration document, however, "pt" would match and hence the following elements would be selected:
<widget xmlns="http://www.w3.org/ns/widgets">
...
<!-- city names in Portuguese -->
<preference name="preferredCity"
value="Lisboa"
xml:lang="pt"/>
<preference name="homeCity"
value="Nova Iorque"
xml:lang="pt"/>
...
</widget> Hence there would be a mismatch in language between the content selected from element-based localization, and content being selected from folder-based localization (unlocalized, which could be in any language). In other words, the end user would be shown localized content from the configuration file in Portuguese, and unlocalized content from the root of the widget package, which in this instance is written in English. This could potentially result in an abnormal user experience. Nevertheless, it is important to explore the possibility of having multiple language tags to represent the widget's locale, so that is the subject of the proposals the next section.
Assuming the optimal way to represent a widget's locale is by using multiple language tags (proposal B1), should the widget's locale also be represented as multiple language tags or as a single language tag? As was exemplified by proposals C3, the difference between supporting single or multiple language tags has significant (and potentially abnormal) effects on the selection of localized content and user experience. Nevertheless, this section describes the possible choices in representing the widget user agent's locale as multiple language tags, and is the subject of the following three proposals.
For each proposal below, consider the following widget file structure and configuration document and assume the user agent's locale is "en-us,fr":
widget.wgt config.xml index.html fun.gif locales/en/fun.gif locales/en-au/fun.gif locales/fr/french.htmllocales/fr/fun.gif
config.xml
<widget xmlns="http://www.w3.org/ns/widgets">
<name>nombre</name>
<name xml:lang="en">name</name>
<description>escrito en español.</description>
<icon src="a.gif"/>
<content xml:lang="fr" src="french.html"/>
<license xml:lang="fr"
href="http://artlibre.org/licence/lal/">
<license href="http://www.opensource.org/licenses/mit-license.php"/>
</widget>PROPOSAL D1: The widget has exactly one locale, and upon performing localized content matching excludes unlocalized content. Unlocalized content is only used in the event that the user agent's locale does not match any localized content in the widget package. This means that only the matching localized content in the range of one language tag will be selected by the user agent. Unlocalized content is only ever used by the user agent if, and only if, no widget locale can be derived by using the user agent's locale. This proposal will cause the user agent to exclude a lot of content and could potentially confuse authors.
Using the example widget above and assuming the widget's locale is "en-us", only the name element with the xml:lang attribute value of "en" would be matched by the user agent. The user agent would ignore the following element because they don't match the widget's locale:
name element, description element, icon element, content element, license elements. Note that an issue that arises here as, technically speaking, the widget is left "unlicensed". "/index.html", as derived from the default start file rule defined in the [P&C spec]. fun.gif" is used in the package, the user agent would display "/locales/en/fun.gif". PROPOSAL D2: The widget has only one locale, but the user agent is permitted to use unlocalized content where it cannot matched to localized content to the widget's locale. This is the editor's preferred proposal as it means that at least some content will be displayed, even if it is unlocalized.
Proposal D2 is useful in practice that it uses unlocalized content as fallback. However, the mixing of localized and unlocalized content could lead to an abnormal user experience.
Using the example widget, the following elements would be matched:
name element with the xml:lang attribute whose value is "en". description element. license element.icon element.The following element would be ignored:
content element with an xml:lang value "fr".license element with an xml:lang value "fr".The start file would be, "/index.html"; derived from default start file rule, as defined in the [P&C spec]. Where "fun.gif" is used, "/locales/en/fun.gif" would win over the one at the root of the package.
Effectively, the end-user would be presented with the following content:
Name: name. (English)
Description: escrito en español. (Spanish)
License: http://www.opensource.org/licenses/mit-license.php (English)
PROPOSAL D3: The widget matches as many of the user agent's locales as possible to the content in the widget package, and also matches all unlocalized content. This means that a mix of matching localized and unlocalized elements from the configuration document and locale folders are matched to compose the content of the widget. The priority that the user agent selects the localized content is based on the order that language tags appear in the user agent's locale, with unlocalized content being selected last.
Using the example widget above:
name element with the xml:lang="en" attribute would be matched and would win over the unlocalized name element. description element would be used.content element with an xml:lang value "fr" would be matched, so the start file would be "/locales/fr/french.html". license element with an xml:lang value "fr" would be matched and would win over the unlocalized license element. icon element would be used.fun.gif" is used, "/locales/en/fun.gif" would win over both "/locales/fr/fun.gif" and the unlocalized "fun.gif" at the root of the widget.The fourth, and final, precondition to achieve i18n is for the user agent to select the appropriate localized or unlocalized content from the widget package. The user agent must then:
As was proposed above, what localized content is used is based on matching the user agent's locale (if any) to content in the configuration document and/or in files within the widget package to derive the widget's locale.
Selecting the appropriate localized content requires the user agent to:
content element, the icon element, and the thumbnail element, etc.).In the latter point above, the user agent will needs to decide what to do when a dereferenced URI addresses a file that is absent in a localized folder. If the user agent searches for missing localized content in alternative locations, it needs to expose the location of content within the widget package to an author in a logical manner.
The [P&C spec] defines a number of elements that require an author to use URIs references to address files within the widget package. These elements include:
content element, through the src attribute.icon element, through the src attribute.thumbnail element, through the src attribute.During Step 7 - Process the Configuration Document, as defined in the [P&C spec], the user agent needs to check if files referenced by these elements exist in the widget package. For those elements, the [P&C spec] only supports two kind of URI references: relative and absolute paths, as defined in the [URI Generic Syntax] specification, so the src attribute cannot address resources outside widget package (i.e., resources on the Web).
How the src attribute of those elements is resolved to a URI is the subject of the following proposals:
PROPOSAL E1: Use [XML Base] to resolve URI references. For this proposal, the configuration document's XML base is dynamically set, prior to processing to the folder that matches the widget's locale. This means that relative URIs are resolved using the rules of the [XML Base] specification. This is the editor's preference.
As an example of E1, consider the following widget file structure and configuration document and assume the user agent's locale is "en, fr":
widget.wgt config.xml index.html a.gif b.gif hello/d.gif locales/en-us/a.gif locales/en-gb/a.gif locales/en-gb/index.html locales/en/a.gif locales/en/c.gifconfig.xml <widget xmlns="http://www.w3.org/ns/widgets"> <name>nombre</name> <description>escrito en español</description> <name xml:lang="en">name</name> <icon src="a.gif"/> <content xml:lang="en" src="index.html"/> <content xml:lang="en-gb" src="index.html"/> </widget>
An illustration of the DOM tree for the config.xml document above is shown below. The purpose is to illustrate the resolved URI references. Note that, as the [P&C spec] does not yet define a URI scheme for widgets, the "widget://" URI scheme is used here as an example only:
widget xmlns="http://www.w3.org/ns/widgets"
xml:base="widget:///locales/en/"
* name
o #text: nombre
* description
o #text: escrito en español
* name xml:lang="en"
o #text: name
* icon src="widget:///locales/en/a.gif"
* content src="widget:///locales/en/index.html"
xml:lang="en"
A problem arises whereby "widget:///locales/en/index.html" does not exist in the package. How the use agent deals with this condition is the topic of the next section.
PROPOSAL E2: Emulate [XML Base] to resolve URI references. For this proposal, the user agent would emulate the behavior of XML base and dynamically resolve URIs in a way that is similar to XML Base. However, how that is archived would need to be specified in the [P&C spec].
Given a relative URI reference for an attribute that exploits element-based localization, a user agent needs to either search for the referenced file within the relevant hierarchy of locale folders or treat the file it is searching for as absent from the widget package.
Consider the following widget. Assume the widget's locale is "en-us-xx" and the file the user agent is searching for is "index.html".
widget.wgt
config.xml
index.html
a.gif
b.gif
hello/d.gif
locales/en-us-xx/a.gif
locales/en-us/a.gif
locales/en-gb/a.gif
locales/en-gb/index.html
locales/en/a.gif
locales/en/c.gif
PROPOSAL F1: The user agent searches for the missing file in the folder hierarchy that matches the widget's locale. If the file is not in the hierarchy of locale folders, then the user agent searches for the file at the root of the widget package. The container for localized content (the folder called "locales") is not searched for missing content. If the missing file is found somewhere in the folder hierarchy of locale folders or at the root of the widget, and no xml:base has been explicitly set by the author for this element, then the user agent must set xml:base of that element to be an alternate locale folder, or to the root of the widget package, that contains the file. This is the editor's preferred proposal.
Using the example widget above, in the case where the src attribute of the content element is "index.html", the user agent would first look in the "/locales/en-us-xx", then in "/locales/en-us", and then in the "/locales/en" folder, but would fail to find the file. So then the user agent would search at the root of the widget, where it would find a that matches the file name of the file it is searching for. The user agent now dynamically sets the xml:base of the content element to the root of the widget.
PROPOSAL F2: The user agent searches for the missing file only in the locale folder that matches the widget's locale. If there is no file in the hierarchy of locale folders, then the user agent behaves as if the file is absent (equiv. to HTTP's 404).
Using the example in the previous section, in the case where the src attribute of the content element is "index.html", the user agent would only look in the "/locales/en-us-xx" folder and fail to find the file. The user agent would treat the file as absent.
As was the case when trying to find missing localized content (section above), there are instances where localized content addressed by a URI will not be found.
Consider the following widget package and index.html file, and assume the widget's locale is "en-us-xx":
widget.wgt
config.xml
index.html
a.gif
b.gif
c.gif
hello/d.gif
locales/en-us-xx/a.gif
locales/en-us/a.gif
locales/en-gb/a.gif
locales/en-gb/index.html
locales/en/a.gif
locales/en/c.gif
index.html
<!doctype html>
<html>
<title>Shoot'em up!</title>
<script>
createBaddy(){
badGuy = new Image();
badGuy.src = "c.gif";
}
</script>
<img src="a.gif" />PROPOSAL G1: The base URI of the start file is set to the folder that matches the widget's locale. The user agent searches for any missing files in the folder hierarchy that matches the widget's locale. If the file is not in the hierarchy of locale folders, then the user agent searches for the file at the root of the widget package. The container for localized content (the folder called "locales") is never searched for missing content. If the file is found, the user agent dynamically rewrites the URI to address the appropriate resource. This is the editor's preferred proposal.
Using the example above, the base URI of the index.html would be "widget:///locales/en-us-xx/", but the user agent would dereference badGuy.src = "c.gif" to "widget:///locales/en/c.gif". The value of badGuy.src would return "locales/en/c.gif".
PROPOSAL G2: The base URI of the start file document is set the folder where the start file resides. The user agent searches for any missing files in the folder hierarchy that matches the widget's locale. If the file is not in the hierarchy of locale folders, then the user agent searches for the file at the root of the widget package. The container for localized content (the folder called "locales") is never searched for missing content.
The base URI of the index.html is "widget:///", but the user agent would dereference badGuy.src = "c.gif" to "widget:///locales/en/c.gif".
Note also that an author can check which locale they are running in by querying the widget.locale DOM attribute, as defined in the Widgets 1.0: APIs and Events specification.
Given the editor's preferences (A2, B1, C1, D2, E1, F1, G1), the Localization Scenario Matrix below lists all the (16) possible localization options for authors. It is important to note that not all scenarios result in a valid widget. The columns of the Localization Scenario Matrix table are label as follows:
xml:lang attribute. xml:lang attribute for it.| scenario | Localized config.xml | provides locale folders | provides unlocalized files | provides unlocalized elements in config | Valid widget |
|---|---|---|---|---|---|
| A | YES | YES | YES | YES | YES |
| B | NO | YES | YES | YES | YES |
| C | NO | NO | YES | YES | YES |
| D | NO | NO | NO | YES | NO |
| E | NO | NO | NO | NO | NO |
| F | YES | NO | NO | NO | NO |
| G | YES | YES | NO | NO | YES (but only if start file is provided) |
| H | YES | YES | YES | NO | YES |
| I | YES | NO | NO | YES | NO |
| J | NO | YES | YES | NO | YES |
| K | NO | YES | NO | YES | NO |
| L | YES | NO | YES | NO | YES |
| M | YES | NO | YES | YES | YES |
| N | YES | YES | NO | YES | YES |
| O | NO | NO | YES | NO | YES |
| P | NO | YES | NO | NO | YES (because of default start file, but can become invalid) |
The 16 scenarios, written in prose, are as follows:
Provides localized elements in config.xml, provides locale folders, provides unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, provides locale folders, provides unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, does not provide locale folders, provides unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, does not provide locale folders, does not provide unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, does not provide locale folders, does not provide unlocalized files, does not provide unlocalized elements in config.
Provides localized elements in config.xml, does not provide locale folders, does not provide unlocalized files, does not provide unlocalized elements in config.
Provides localized elements in config.xml, provides locale folders, does not provide unlocalized files, does not provide unlocalized elements in config.
Provides localized elements in config.xml, provides locale folders, provides unlocalized files, does not provide unlocalized elements in config.
Provides localized elements in config.xml, does not provide locale folders, does not provide unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, provides locale folders, provides unlocalized files, does not provide unlocalized elements in config.
Does not provide localized elements in config.xml, provides locale folders, does not provide unlocalized files, provides unlocalized elements in config.
Provides localized elements in config.xml, does not provide locale folders, provides unlocalized files, does not provide unlocalized elements in config.
Provides localized elements in config.xml, does not provide locale folders, provides unlocalized files, provides unlocalized elements in config.
Provides localized elements in config.xml, provides locale folders, does not provide unlocalized files, provides unlocalized elements in config.
Does not provide localized elements in config.xml, does not provide locale folders, provides unlocalized files, does not provides unlocalized elements in config.
Does not provide localized elements in config.xml, provides locale folders, does not provide unlocalized files, does not provides unlocalized elements in config.
Examples of how each scenario plays out from the author's perspective are the subject of each of the following sub-sections. Observations are made about each scenario, as well as proposals as how issues can be overcome.
This is the ultimate localization scenario, where all localization features provided by the [P&C spec] are exploited.
In this scenario, the widget looks like:
wigdet.wgt
fun.html
config.xml
foobar.png
icon.gif
locales/en-us/icon.gif
locales/en-us/foobar.png
locales/it/icon.gif
locales/it/foobar.gif
locales/it-it/fun.htmlConfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="it-it">example</name>
<name>example</name>
<icon src="icon.gif" />
<content src="fun.html" />
</widget>
To get the icon element's src to match all case, xml:base of the icon element must be set the to the location of the base folder. In cases where there is no localization match, the xml:base must be set to the root of the package.
To get the content element to match, in all cases but the Italian case ("it-it"), the xml:base attribute of the content element must be set to the root of the package.
locales/it-it/fun.html looks like:
<html> ... <img src="foobar.png">
In this scenario, the widget looks like:
wigdet.wgt
index.html
config.xml
foobar.png
icon.gif
locales/en-us/icon.gif
locales/it-it/icon.gifConfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>example</name>
<icon src="icon.gif" />
</widget>Index.html looks like
<html>
...
<img src="foobar.png"> This is effectively and unlocalized widget.
In this scenario, the widget looks like:
wigdet.wgt
index.html
config.xml
foobar.png
icon.gifconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>example</name>
<icon src="icon.gif" />
</widget>Index.html looks like
<html>
...
<img src="foobar.png"> This scenario the widget would contain only a config file, hence an invalid widget.
In this scenario, the widget looks like:
wigdet.wgt
config.xmlconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>example</name>
<icon src="icon.gif" />
</widget>Index.html looks like:
<html>
...
<img src="foobar.png"> This widget would be empty and hence an invalid widget.
In this scenario, the widget looks like:
wigdet.wgt
config.xmlconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets"/>
This widget does not contain a start file, hence it is invalid.
PROPOSAL: Make a start file mandatory at the root of the widget.
In this scenario, the widget looks like:
wigdet.wgt
config.xmlconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name>example</name>
</widget>Index.html looks like:
<html>
...
This widget is unless a user agent was able to match one of the languages, then this would be an invalid widget.
PROPOSAL: Make a start file mandatory at the root of the widget.
In this scenario, the widget looks like:
wigdet.wgt config.xmllocales/en-us/index.html locales/en-us/image.png locales/it-it/index.html
configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="jp">
<name>example</name>
</widget>Index.html looks like:
<html>
<p>hello</p>
<img src="image.png"/>In this scenario, no information can be provided for unlocalized widgets.
In this scenario, the widget looks like:
wigdet.wgt
index.html
config.xml
foobar/style.css
locales/en-us/image.pngconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="jp">
<name>example</name>
</widget>index.html looks like:
<html>
<link href="/foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>This widget is invalid, it does not contain a start file.
PROPOSAL: Make a start file mandatory at the root of the widget.
In this scenario, the widget looks like:
wigdet.wgt
config.xml configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="jp">example</name>
<name>example</example>
</widget>
In this scenario, the unlocalized configuration document elements would be shown for all elements. There is a risk that this widget could become invalid if no index.html is added to the root of the widget package.
In this scenario, the widget looks like:
wigdet.wgt
index.html
config.xml
foobar/style.css
locales/en-us/index.html
locales/en-us/image.png
locales/it-it/index.htmlconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>example</name>
</widget>index.html looks like:
<html>
<link href="/foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>If no match is made on language, this will result in an invalid widget.
PROPOSAL: Make start file mandatory at the root.
In this scenario, the widget looks like:
wigdet.wgt
config.xml
locales/en-us/index.html
locales/en-us/foobar/style.css
locales/en-us/image.pngconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name>example</name>
</widget>index.html looks like:
<html>
<link href="foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>As there is no match on language, this widget would not show any information from the configuration document.
ISSUE: need to decide what to do in these situations, do we show nothing or something?
PROPOSAL: We show nothing.
In this scenario, the widget looks like:
wigdet.wgt
config.xml
index.html
foobar/style.css
image.pngconfiguration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets"
xml:lang="en">
<name>example</name>
</widget>index.html looks like:
<html>
<link href="foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>In this scenario, no folder-based localization is performed. Localized metadata is still displayed to the user.
In this scenario, the widget looks like:
wigdet.wgt config.xml index.html icon.gif images/foobar.png
configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="en">example</name>
<name xml:lang="es">ejemplo</name>
<name>example</name>
<icon src="icon.gif" />
</widget>Index.html looks like
<html>
...
<img src="images/foobar.png"> This widget is valid. Unlocalized metadata can still be shown for when no languages are matched. Widget gets treated as invalid if i18n fails.
In this scenario, the widget looks like:
wigdet.wgt config.xml locales/en-us/index.html locales/en-us/icon.gif locales/it-it/index.htmllocales/it-it/icon.gif
configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets">
<name xml:lang="en">example</name>
<name>example</name>
<icon src="icon.gif" />
</widget>Index.html looks like
<html>
...
<img src="foobar.png"> Widget is valid, but no metadata in configuration document is supplied.
In this scenario, the widget looks like:
wigdet.wgt config.xmlindex.html foobar/style.css image.png
configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets" />index.html looks like:
<html>
<link href="foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>This widget is still valid because of default start file matching. However, no metadata is provided. No default start file fallback is provided.
Issue: widget will be treated as invalid if that locale folder cannot be matched.
In this scenario, the widget looks like:
wigdet.wgt config.xmllocales/en-us/index.html locales/en-us/foobar/style.css locales/en-us/image.png
configuration document looks like:
<widget xmlns="http://www.w3.org/ns/widgets" />index.html looks like:
<html>
<link href="foobar/style.css" rel="stylesheet" type="text/css"/>
<p>hello</p>
<img src="image.png"/>The editor would like the thanks the following people for providing feedback and helping improve this document: