git.gag.com Git - debian/openrocket/blob - core/src/net/sf/openrocket/l10n/Translator.java

   1 package net.sf.openrocket.l10n;
   2
   3 import java.util.MissingResourceException;
   4
   5 /**
   6  * An interface for obtaining translations from logical keys.
   7  * <p>
   8  * Translator implementations must be thread-safe.
   9  *
  10  * @author Sampo Niskanen <sampo.niskanen@iki.fi>
  11  */
  12 public interface Translator {
  13
  14         /**
  15          * Retrieve a translated string based on a logical key.  This always returns
  16          * some string, potentially falling back to the key itself.
  17          *
  18          * @param key   the logical string key.
  19          * @return              the translated string.
  20          * @throws MissingResourceException if the translation corresponding to the key is not found.
  21          * @throws NullPointerException if key is null.
  22          */
  23         public String get(String key);
  24
  25
  26         /**
  27          * Retrieve a translated string based on a base key and base (English) version of the text.
  28          * The base text is normalized before using as a key.
  29          * <p>
  30          * This is meant to be used in very specific cases where the English name is
  31          * used as a key for translation and storage.  If a translation is not found,
  32          * the base text is used instead.
  33          *
  34          * @param base          the base for the logical key
  35          * @param text          the base (English) text to translate
  36          * @return                      the translated string, or "text" if not found
  37          */
  38         public String get(String base, String text);
  39
  40
  41         /**
  42          * Find the base (English) version of a translated text.
  43          * <p>
  44          * This is the opposite operation of {@link #get(String, String)}, and
  45          * meant for use in very specific cases when storing the values of
  46          * translated texts.
  47          *
  48          * @param base                  the base for the logical key
  49          * @param translation   the translated string
  50          * @return                              the base text, or the translation if not found.
  51          */
  52         public String getBaseText(String base, String translation);
  53
  54 }