org.gwtproject.i18n.shared.Localizable Maven / Gradle / Ivy

/*
 * Copyright © 2018 The GWT Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You 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.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.gwtproject.i18n.shared;

import java.lang.annotation.*;

/**
 * A tag interface that serves as the root of a family of types used in static internationalization.
 * Using GWT.create(class) to instantiate a type that directly extends or
 * implements Localizable invites locale-sensitive type substitution.
 *
 * Locale-sensitive Type Substitution
 *
 * If a type Type directly extends or implements Localizable (as opposed
 * to {@link org.gwtproject.i18n.client.Constants} or {@link org.gwtproject.i18n.client.Messages})
 * and the following code is used to create an object from Type as follows:
 *
 * Type localized = (Type)GWT.create(Type.class);
 *
 * then localized will be assigned an instance of a localized subclass, selected based
 * on the value of the locale client property. The choice of subclass is determined by
 * the following naming pattern:
 *
 * 
 *
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 *
 * If locale is...     The substitute class for Type is...
unspecified Type itself, or Type_ if Type
 * is an interface
x Class Type_x if it exists, otherwise treated as if
 * locale were unspecified
x_Y Class Type_x_Y if it exists, otherwise treated as if
 * locale were x
 *
 * where in the table above x is a ISO language code and Y
 *  is a two-letter ISO country code.
 *
 * Specifying Locale
 *
 * The locale of a module is specified using the locale client property, which can be
 * specified using either a meta tag or as part of the query string in the host page's URL. If both
 * are specified, the query string takes precedence.
 *
 * To specify the locale client property using a meta tag in the host HTML, use
 * gwt:property as follows:
 *
 * 
<meta name="gwt:property" content="locale.new=x_Y">
 *
 * For example, the following host HTML page sets the locale to "ja_JP":
 *
 * {@gwt.include com/google/gwt/examples/i18n/ColorNameLookupExample_ja_JP.html}
 *
 * 
To specify the locale client property using a query string, specify a value for
 * the name locale. For example,
 *
 * 
http://www.example.org/myapp.html?locale=fr_CA
 *
 * For More Information
 *
 * See the GWT Developer Guide for an introduction to internationalization.
 *
 * @see org.gwtproject.i18n.client.Constants
 * @see org.gwtproject.i18n.client.ConstantsWithLookup
 * @see org.gwtproject.i18n.client.Messages
 * @see org.gwtproject.i18n.client.Dictionary
 */
@Localizable.I18nLocaleSuffuxes({"default", "en", "es", "fr", "de"}) // TODO real list
public interface Localizable {
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @Documented
  @interface IsLocalizable {}

  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @Documented
  @interface I18nLocaleSuffuxes {
    String[] value();
  }
}
If `locale` is...	The substitute class for `Type` is...
unspecified	`Type` itself, or `Type_` if `Type` * is an interface
`x`	Class `Type_x` if it exists, otherwise treated as if * `locale` were unspecified
`x_Y`	Class `Type_x_Y` if it exists, otherwise treated as if * `locale` were `x`