Package com.smartgwt.client.docs

Interface I18n

public interface I18n

Internationalization and Localization

Internationalizing Smart GWT Applications

Internationalizing a Smart GWT application involves creating locale-specific versions of all strings, images, and possibly colors. In some cases, component layout may be affected as well (for example date field order differs between some locales).

Character Encodings

In order to deliver content in different languages to the browser and have it be displayed correctly, it is important that the browser and server agree on the character encoding being used to send the page.

Generally speaking, you can use whatever character encoding you prefer, so long as you're consistent about serving your files to the browser with exactly the same encoding as was used to save the file to disk. Keep in mind though that the character encoding you choose must be supported by all browsers you intend to support. Isomorphic recommends that, where possible, you use the UTF-8 encoding. Regardless of which character encoding you choose, keep in mind that for the browser to correctly display non-ASCII characters, you must explicitly set the character encoding of your page to match the encoding you used to save the file. Browsers have built-in heuristics to guess the character encoding, but they can't be relied upon to work 100% of the time.

There are two ways to explicitly tell the browser what character encoding is being used for a given page. One is to set the "Content-Type" HTTP header, for example: 

  Content-Type: text/html; charset=UTF-8
If you're using JSP on the back-end, you can set this header as follows: 
  <%@ page contentType="text/html; charset=UTF-8"%>
Or using Java Servlet APIs in a Servlet as follows: 
  response.setContentType("text/html; charset=UTF-8");
Note that the latter needs to be done before any content is written to the response output stream.

The other approach to setting the content encoding is to use an HTML META tag to embed it in the page itself (note that this applies to HTML documents only). The META tag must go inside the <HEAD> HTML element - e.g. as follows: 

  <HEAD>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
  </HEAD>
In addition, for a .html or other static (non-.jsp) file, you must also ensure that the file itself is saved in UTF-8 encoding. Advanced text editors (including the Eclipse IDE) can show you the encoding of a text file and allow you to change it. In Eclipse this is in the Preferences area (search for "Encoding") and UTF-8 is not the default for .html files, and should be changed.

Isomorphic recommends that you follow all of the above approaches for maximum compatibility. For example, if you omit the META tag approach, pages saved by the user using the browser save function may not render correctly when subsequently read from disk because HTTP headers are not available in that context. Conversely, not providing the HTTP header or not saving the file in UTF-8 can result in application servers delivering the file in the encoding in which it is saved, or in their own default and incorrect content encoding.

If you're using a given character encoding pervasively in your pages, you can also configure your web server or application server to use that character encoding as the default for all pages of a given mime type or some other criteria (depending on the capability of your server) - for example on a per-directory basis.

For more information on character encodings, character sets, and working with HTML, please see W3C's tutorial here: http://www.w3.org/International/tutorials/tutorial-char-enc/

NOTE: Default Encoding

As mentioned above, Isomorphic recommends the use of UTF-8 encoding. However, it is not possible to configure some servlet engines to do this by default. Both Tomcat and Jetty default to the ISO-8859-1 character set (commonly known as Latin-1), even if the Java VM specifies a different encoding (the Tomcat documentation claims that this behavior is a requirement of the Servlet specification).

To work around this, we change charset encoding to UTF-8 on every request/response that goes through two core Isomorphic servlets: IDACall and DataSourceLoader. If you need to change this, you can do so by adding init-param settings to your web.xml file. Please see the Javadocs for those two servlets for examples of how to do this.

Framework Message Localization

Smart GWT components include standard prompts and error messages in various cases, and all such messages support localization.

SmartGWT ships with pre-built language packs for many languages. These are automatically used by the framework: all you have to do is ensure that the appropriate locale has been set using one of the standard GWT mechanisms. In brief, either:

  • Add a meta tag to your bootstrap page: <meta name="gwt:property" content="locale=ja_JP">
  • Specify the locale in a query parameter: http://www.example.org/myapp.html?locale=fr_CA

If you find that the language pack you are using has any incorrect or missing translations, or you want to add a new language pack, please visit this forums thread for instructions on how to contribute translations so that they will be added to future Smart GWT builds.

You can alternatively maintain your own private additions or overrides to the default language packs. Use the standard GWT technique for selectively overriding Messages: create a subclass of SmartGwtMessages that overrides specific methods, and a .properties file with your overridden messages. Then create your overridden Messages instance and call I18nUtil.initMessages() with it. For example: 

     public class CustomizedSgwtMessages extends com.smartgwt.client.i18n.SmartGwtMessages {
        // override button_title
        String button_title();
     }
    
     // then in a new file CustomizedSgwtMessages.properties
     button_title=My Title
 
     // and in a new file CustomizedSgwtMessages_fr.properties
     button_title=French translation
 
     // then in your onModuleLoad() call
     CustomizedSgwtMessages myMessages = GWT.create(CustomizedSgwtMessages);
     I18nUtil.initMessages(myMessages);

Application Message Localization

String localization in SmartGWT is best done using standard GWT approaches. Although GWT supports various ways of localizing strings, Isomorphic recommends the use of an approach based on Resource Bundles. Other parts of SmartGWT - for example, .ds.xml files - are best localized using resource bundles, so using resource bundles makes it easier to share messages that are used both client and server side.

Localizing Server-side Error Messages

If you are providing error messages from server-side code, use standard Java techniques to determine the locale (servletRequest.getLocale()) and load ResourceBundles. Note that if you are using DMI validation, the HttpServletRequest is available via the standard DMI approach: just declare it as an additional parameter, and it is provided.

Support for Right-to-Left (RTL) languages

Smart GWT includes support for RTL languages. To enable, simply set dir="rtl" on the HTML element: 

     <HTML dir="rtl">
ListGrid columns, horizontal layouts, scrolling directions, etc will reverse order automatically.

Because RTL in some cases requires additional media files, RTL is only supported for the Enterprise, EnterpriseBlue and Graphite skins.

DataSource and Component XML localization

Please see the separate article on DataSource and Component XML Localization

Localized Number and Currency Formatting

Please see the separate article on Localized Number Formatting

Resources:

Java

.NET

PHP