Google Web Toolkit
Search Google Code:

# Internationalization

GWT includes a flexible set of tools to help you internationalize your applications and libraries. GWT internationalization support provides a variety of techniques to internationalize strings, typed values, and classes.

## Getting Started

Since GWT supports a variety of ways of internationalizing your code, begin by researching which approach best matches your development requirements.

Are you writing code from scratch?
If so, you'll probably want to read up on GWT's static string internationalization techniques.

Do you want to internationalize mostly settings or end-user messages?
If you have mostly settings (the kind of thing for which you'd normally use simple properties files), consider Constants. If you have a lot a of end-user messages, then Messages is probably what you want.

Do you have existing localized properties files you'd like to reuse?
The i18nCreator tool can automatically generate interfaces that extend either Constants or Messages.

Are you adding GWT functionality to an existing web application that already has a localization process defined?
Dictionary will help you interoperate with existing pages without requiring you to use GWT's concept of locale.

Do you really just want a simple way to get properties files down to the client regardless of localization?
You can do that, too. Try using Constants without specifying a locale.

## Internationalization Techniques

GWT offers multiple internationalization techniques to afford maximum flexibility to GWT developers and to make it possible to design for efficiency, maintainability, flexibility, and interoperability in whichever combinations are most useful.

Static string internationalization refers to a family of efficient and type-safe techniques that rely on strongly-typed Java interfaces, properties files, and code generation to provide locale-aware messages and configuration settings. These techniques depend on the interfaces Constants and Messages.

At the other end of the spectrum, dynamic string internationalization is a simplistic and flexible technique for looking up localized values defined in a module's host page without needing to recompile your application. This technique is supported by the class Dictionary.

Using an approach similar to static string internationalization, GWT also supports internationalizing sets of algorithms using locale-sensitive type substitution. This is an advanced technique that you probably will not need to use directly, although it is useful for implementing complex internationalized libraries. For details on this technique, see Localizable.

## The I18N Module

The core types related to internationalization reside in the `com.google.gwt.i18n` package:

- Constants
  Useful for localizing typed constant values
- Messages
  Useful for localizing messages requiring arguments
- ConstantsWithLookup
  Like Constants but with extra lookup flexibility for highly data-driven applications
- Dictionary
  Useful when adding a GWT module to existing localized web pages
- Localizable
  Useful for localizing algorithms encapsulated in a class

The GWT internationalization types are included in the module `com.google.gwt.i18n.I18N`. To use any of these types, your module must inherit from it:

    <!--                                                                        -->
    <!-- Copyright 2007 Google Inc.                                             -->
    <!-- Licensed under the Apache License, Version 2.0 (the "License"); you    -->
    <!-- may not use this file except in compliance with the License. You may   -->
    <!-- may obtain a copy of the License at                                    -->
    <!--                                                                        -->
    <!-- http://www.apache.org/licenses/LICENSE-2.0                             -->
    <!--                                                                        -->
    <!-- Unless required by applicable law or agreed to in writing, software    -->
    <!-- distributed under the License is distributed on an "AS IS" BASIS,      -->
    <!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        -->
    <!-- implied. License for the specific language governing permissions and   -->
    <!-- limitations under the License.                                         -->

    <module>
      <!-- other inherited modules, such as com.google.gwt.user.User -->
      <inherits name="com.google.gwt.i18n.I18N"/>
      <!-- additional module settings -->
    </module>

## Specifics

- Static String Internationalization
  A type-safe and optimized approach to internationalizing strings.
- Dynamic String Internationalization
  A flexible and simplistic method of internationalizing strings that easily integrates with existing web applications that do not support the GWT `locale` client property.
- Specifying a Locale
  How to add locales and specify the `locale` client property during deployment.
- Localized Properties Files
  How to create localized properties files for use with Constants or Messages