001: /*
002: * Copyright 2007 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016:
017: package com.google.gwt.i18n.client;
018:
019: /**
020: * A tag interface that serves as the root of a family of types used in static
021: * internationalization. Using <code>GWT.create(<i>class</i>)</code> to
022: * instantiate a type that directly extends or implements
023: * <code>Localizable</code> invites locale-sensitive type substitution.
024: *
025: * <h3>Locale-sensitive Type Substitution</h3>
026: * If a type <code>Type</code> directly extends or implements
027: * <code>Localizable</code> (as opposed to
028: * {@link com.google.gwt.i18n.client.Constants} or
029: * {@link com.google.gwt.i18n.client.Messages}) and the following code is used
030: * to create an object from <code>Type</code> as follows:
031: *
032: * <pre class="code">Type localized = (Type)GWT.create(Type.class);</pre>
033: *
034: * then <code>localized</code> will be assigned an instance of a localized
035: * subclass, selected based on the value of the <code>locale</code> client
036: * property. The choice of subclass is determined by the following naming
037: * pattern:
038: *
039: * <table>
040: *
041: * <tr>
042: * <th align='left'>If <code>locale</code> is...    </th>
043: * <th align='left'>The substitute class for <code>Type</code> is...</th>
044: * </tr>
045: *
046: * <tr>
047: * <td><i>unspecified</i></td>
048: * <td><code>Type</code> itself, or <code>Type_</code> if <code>Type</code>
049: * is an interface</td>
050: * </tr>
051: *
052: * <tr>
053: * <td><code>x</code></td>
054: * <td>Class <code>Type_x</code> if it exists, otherwise treated as if
055: * <code>locale</code> were <i>unspecified</i></td>
056: * </tr>
057: *
058: * <tr>
059: * <td><code>x_Y</code></td>
060: * <td>Class <code>Type_x_Y</code> if it exists, otherwise treated as if
061: * <code>locale</code> were <code>x</code></td>
062: * </tr>
063: *
064: * </table>
065: *
066: * where in the table above <code>x</code> is a <a
067: * href="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO language
068: * code</a> and <code>Y</code> is a two-letter <a
069: * href="http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">ISO
070: * country code</a>.
071: *
072: * <h3>Specifying Locale</h3>
073: * The locale of a module is specified using the <code>locale</code> client
074: * property, which can be specified using either a meta tag or as part of the
075: * query string in the host page's URL. If both are specified, the query string
076: * takes precedence.
077: *
078: * <p>
079: * To specify the <code>locale</code> client property using a meta tag in the
080: * host HTML, use <code>gwt:property</code> as follows:
081: *
082: * <pre><meta name="gwt:property" content="locale=x_Y"></pre>
083: *
084: * For example, the following host HTML page sets the locale to "ja_JP":
085: *
086: * {@gwt.include com/google/gwt/examples/i18n/ColorNameLookupExample_ja_JP.html}
087: * </p>
088: *
089: * <p>
090: * To specify the <code>locale</code> client property using a query string,
091: * specify a value for the name <code>locale</code>. For example,
092: *
093: * <pre>http://www.example.org/myapp.html?locale=fr_CA</pre>
094: *
095: * </p>
096: *
097: * <h3>For More Information</h3>
098: * See the GWT Developer Guide for an introduction to internationalization.
099: *
100: * @see com.google.gwt.i18n.client.Constants
101: * @see com.google.gwt.i18n.client.ConstantsWithLookup
102: * @see com.google.gwt.i18n.client.Messages
103: * @see com.google.gwt.i18n.client.Dictionary
104: */
105: public interface Localizable {
106: }
|