Interface TranslationPackage

All Known Subinterfaces:
MutableTranslationPackage
All Known Implementing Classes:
BasicTranslationPackage, ClientLocalizationManager, ClientLocalizationManagerImpl, ComponentTranslationPanel.DelegateTranslationPackage, DesignerLocalizationManager, ImmutableTranslationPackage, TranslationPackageDiff

public interface TranslationPackage
A translation package holds the keys and one or more translations for the keys.
  • Field Details

    • NOTES_IDENTIFIER

      static final String NOTES_IDENTIFIER
      Reserved pseudo-locale identifier under which per-key editorial notes are stored rather than a real locale's translations. The translation archive formats use it as a file/worksheet name (see the io package).
      See Also:
    • BASE_LOCALE

      static final Locale BASE_LOCALE

      The language in which translation keys are authored: English. Keys are effectively the source-language strings, so every package implicitly "contains" this locale even when no bundle /// is stored for it. Concretely, it is:

      • always included in getAvailableLocales();
      • treated as defined by isDefined(String, Locale) as soon as the key exists in the index, with no separate translation required; and
      • the locale assumed when a null locale is passed to a bundle lookup.

      This is a fixed constant, not a per-package setting. Note that lookups for other locales fall back to the raw key text, not to this locale's translations.

  • Method Details

    • getKeyHashRule

      @Nullable KeyHashRule getKeyHashRule()
      The key hash rule dictates how key equivalency is calculated. Though this field should not be used to look up keys, it's important that derived translation packages use the same rule.
    • getAvailableLocales

      Collection<Locale> getAvailableLocales()
      Returns:
      the locales for which translations are available. This always includes BASE_LOCALE, the language in which keys are defined.
    • isDefined

      boolean isDefined(String key)
      Returns whether the key is defined in the package. A key can be defined without any particular translations.
    • isDefined

      boolean isDefined(String key, Locale l)
      Returns whether there is a translation defined for the given key in the given locale.
    • get

      String get(Locale locale, String key)
      Translates the given key into the requested locale.
      Parameters:
      locale - the locale to find a match for
      key - the key to find a match for
      Returns:
      the translation of the key for the requested locale, or the key itself if no translation is available.
    • getStrict

      @Nullable String getStrict(Locale locale, String key)
      Translates the given key into the requested locale, returning null if no translation exists.
      Parameters:
      locale - the locale to find a value for
      key - the key to find a match for
      Returns:
      the translation, or null if the translation doesn't exist.
    • getTranslationsFor

      @Nullable TranslationMap getTranslationsFor(String key)
      Returns:
      a map of all the translations available for a given key.
    • getAvailableKeys

      @Nullable Collection<String> getAvailableKeys()
      Returns:
      all the defined keys.
    • getNote

      @Nullable String getNote(String key)
      Returns the editorial note associated with the given key, or null if there is none. Notes are per-key metadata keyed by the raw key string.
    • getNotes

      Map<String,String> getNotes()
      Returns:
      an unmodifiable view of all notes, keyed by the raw key string. Never null; may be empty.
    • createDiff

      Creates an empty, modifiable diff that respects the same rules as this translation package. A diff is used to track changes relative to this package.
      Returns:
      a new TranslationPackageDiff.
    • getAllTranslations

      @Nullable Iterator<Translation> getAllTranslations()
      Returns:
      an iterator that goes through all the translations. Does not include defined keys that have no translations.
    • getResolvedTranslations

      default Map<String,String> getResolvedTranslations(Locale locale)

      Resolves every translation for the requested locale, following the locale fallback chain (e.g. es_MX then es) so a regional-variant request still picks up translations stored only under the base language. A more-specific locale's translation overrides its base-language fallback, and keys with no translation anywhere in the chain are omitted, so every value in the returned map is non-null.

      This default implementation is expressed purely in terms of getAvailableKeys() and getStrict(Locale, String); implementations that can resolve a whole locale more cheaply (for example by reading their per-locale storage directly) should override it.

      Parameters:
      locale - the locale to resolve, including its fallback chain.
      Returns:
      a fresh, mutable map of raw source key to translation. Never null; may be empty.