public interface DataSourceLocalization
DataSourceLoaderservlet, can instead be internationalized using an approach similar to the internationalization of JSP files with JSTL tags. This approach is also supported for screens defined using
Note: The tags we use for internationalizing Smart GWT XML files look like standard JSTL tags; this is intentional, simply because developers are familiar with JSTL. However, the tags are being processed by Smart GWT code, not JSTL, so only the specific tags documented here are supported.
Given the following DataSource located in /shared/ds/supplyItem.ds.xml:
<DataSource ID="supplyItem"> <fields> <field name="itemName"> <title>Item Name</title> <validators> <Validator type="lengthRange" max="40"> <errorMessage>Must be 40 characters or less.</errorMessage> </Validator> </validators> </field> </fields> </DataSource>To localize the title and validator error string of the
itemNamefield, change the DataSource definition as follows:
<DataSource ID="supplyItem" xmlns:fmt="WEB-INF/"> <fields> <field name="itemName"> <title><fmt:message key="itemTitle"/></title> <validators> <Validator type="lengthRange" max="40"> <errorMessage><fmt:message key="itemLengthRangeValidator"/></errorMessage> </Validator> </validators> </field> </fields> </DataSource>This will cause Smart GWT Server to look for a ResourceBundle called "supplyItem", containing keys "itemTitle" and "itemLengthRangeValidator", and replace the
<fmt:message>tags with the values from the resource bundle in the expected way. It obtains the user's
Localefrom the servlet request, but you can override this if you want to force an application-specific locale, regardless of the user's operating system settings. To do this, specify a "locale" parameter on HTTP requests to the
IDACallservlets (the latter is typically done via
The locale parameter should be an underscore-separated string conforming to the rules described in this article on Java internationalization. For example, "fr" (French language) or "en_US" (English language, US location).
As mentioned, Smart GWT Server will look for a
"supplyItem" in this case because it defaults to the name of the DataSource. It is
possible to override this default at both the DataSource and field levels:
<fmt:bundle>as a top-level DataSource tag, like this:
<DataSource xmlns:fmt="WEB-INF/" ID="supplyItem"> <fmt:bundle basename="com.isomorphic.test.i18n" /> ... </DataSource>
<fmt:message>tags, like this:
<title><fmt:message key='title1' bundle="com.mycompany.MyProperties" /></title>
com.mycompanypackage. For unqualified names (including the default of the DataSource name that we use in the absence of an override), we look in the so-called "default package", which corresponds to the root of your classes directory or the root of a .JAR file.
Note that the
xmlns:fmt attribute in the DataSource definition is required by
the XML parser if you intend to use our
fmt:message features. However, the
actual value you use is unimportant as long as it is present.
Although these examples don't show it, note that it is also possible to internationalize DataSource-level values in the same way as field-level values - for example:
<DataSource xmlns:fmt="WEB-INF/" ID="i18nTest"> <title><fmt:message key="dsTitle" /></title> ... </DataSource>
Note that any amount of whitespace around <fmt> tag is ignored, unless there is also some text, then whitespace becomes significant as well. A declaration like this one:
<DataSource xmlns:fmt="WEB-INF/" ID="i18nTest"> <title> Some text <fmt:message key="dsTitle" /> </title> ... </DataSource>.. will cause linefeed / carriage return characters to be embedded in your title as well as the text. This can be useful in situations where you want to embed small amounts of static text in a localized attribute, but most of the time, you will want the <fmt> tag on one line with the surrounding tag (eg "title").
If any HTML tags are needed around a <fmt> value, you can place them into the resource bundle or use the CDATA section to escape them in the XML file:
<DataSource xmlns:fmt="WEB-INF/" ID="i18nTest"> <title><![CDATA[<b>]]><fmt:message key="dsTitle" /><![CDATA[</b>]]></title> ... </DataSource>
.propertiesfiles be encoded with ISO-8859-1 - in other words, that they be plain ASCII files. This means that any non-ASCII characters have to be escaped, like so: ሴ. For languages like Russian or Japanese, that are based on completely non-ASCII character sets, this obviously leads to
.propertiesfiles that are entirely escaped references, and are not human-readable. Although the
nativetoasciitool is provided with Java to make the creation of these escaped files less tedious, it is still inconvenient that this "compilation step" is required.
Smart GWT avoids the need for this when localizing DataSources and Component XML by
.properties files encoded with UTF-8. To make use of this:
.propertiesfile with UTF-8, preferably without a BOM (Byte Order Marker). Smart GWT Server will simply ignore the BOM in a
.propertiesfile if it is present, but you may see odd behavior from other software if the BOM is present in other types of file - for example, JSP snippets that are included in other pages. The BOM has no meaning in a UTF-8 file anyway, so we recommend just omitting it from all your UTF-8 files (though note that doing this may confuse some editing software, particularly on Windows)
<fmt:bundle>tag, specify an
encodingattribute. There are only two supported values for this attribute: "utf-8" and "iso-8859"
<fmt:message>tags, just like to can override the bundle to use. Again, just specify an
i18n.resourceBundle.parse.utf-8to true in your
server.propertiesfile. This prevents you from having to explicitly specify
encoding="utf-8"in all your
.propertiesfiles are located and parsed by Smart GWT framework code when
encoding="utf-8"is in force. Our parsing code only supports the naming conventions explained in the article linked to above; specifically, it does not support the additional "script" and "extension" elements introduced in Java 7. File names must be of the form "basename_language_COUNTRY_VARIANT", where "COUNTRY" and "VARIANT" are optional. Examples: "fr", "en_US", "en_GB_POSIX"
Component XML. For example:
<isomorphicXML xmlns:fmt="WEB-INF/"> <fmt:bundle basename="com.isomorphic.test.i18n.test" /> <Window ID="testWin1"> <title><fmt:message key='title1' /></title> </Window> </isomorphicXML>Note the following differences between localizing
.ds.xml(DataSource) files and localizing
.ui.xml(component XML) files:
<isomorphicXML>tag, which is ordinarily only used to wrap multiple widget definitions to give a valid XML file, is required if you are using this internationalization technique.
.ui.xmlfile, there is no default bundle like there is with DataSource definitions. Instead, you have to specify the bundle by hand, either by adding a
<fmt:bundle>tag as an immediate child of the
<isomorphicXML>tag, or by specifying
bundleattributes in your individual
ScreenLoaderServlet(this is done for you when you pass a locale to the
<fmt:message key="message_key">. Getting similar value instead of localized message means that either
bundlecould not be found or the
keyis incorrect, look for warnings in server logs for specific details.