Package limn.i18n

Class PropertyBundle

java.lang.Object
limn.i18n.PropertyBundle
All Implemented Interfaces:
StringBundle
public final class PropertyBundle extends Object implements StringBundle
A StringBundle backed by UTF-8 .properties files on the classpath, one family per domain: 

 I18n.addBundle(PropertyBundle.family("/i18n/common"));
 I18n.addBundle(PropertyBundle.family("/i18n/settings"));   // one per screen
 I18n.addBundle(PropertyBundle.family("/i18n/editor"));     // as many as it takes

A family is base.properties plus one file per language tag, and a locale is served by merging them least-specific first (base, then _pt, then _pt-BR), so a regional file carries only what it changes and a language file carries the rest. Underscores are accepted in place of the hyphen (_pt_BR), since that is how the JDK spells the same thing.

Files are read in prepare(java.util.Locale), which I18n calls before anything can ask for a string; lookup(java.lang.String, java.util.Locale) is then a hash get. A missing file is not an error; it is simply a language this domain does not translate, and the caller's English stands.

UTF-8, not ISO-8859-1: these files are read through a Reader, so Japanese and Cyrillic go in literally instead of as \\uXXXX escapes.

  • Method Details

    • family

      public static PropertyBundle family(String baseResourcePath)
      A family rooted at baseResourcePath, resolved against the class loader that loaded this class.
      Parameters:
      baseResourcePath - an absolute classpath path without the .properties suffix; "/i18n/settings" finds /i18n/settings_pt-BR.properties

    • family

      public static PropertyBundle family(String baseResourcePath, ClassLoader loader)
      A family loaded through a specific class loader, for modular or plugin layouts.

    • of

      public static StringBundle of(Locale locale, Map<String,String> strings)
      A bundle holding one locale's strings directly, for translations that were downloaded, generated, or assembled in a test rather than shipped as a file.

    • prepare

      public void prepare(Locale locale)
      Description copied from interface: StringBundle
      Loads whatever answering locale will need. Called by I18n.setLocale(java.util.Locale), I18n.addBundle(limn.i18n.StringBundle) and I18n.retainLocale(java.util.Locale) before listeners are notified, which is the whole point of the method: without it a file-backed bundle would read from disk lazily, and the first read would land inside the measure pass of the frame that switches the language.

      More than one locale may be prepared at a time: the process locale, and every retained subtree locale. A bundle that keeps per-locale state keeps it for each until StringBundle.release(java.util.Locale) says otherwise.

      Must not throw for a locale it cannot serve; a missing translation is StringBundle.lookup(java.lang.String, java.util.Locale) returning null, not a failure.

      Specified by:
      prepare in interface StringBundle

    • release

      public void release(Locale locale)
      Description copied from interface: StringBundle
      Drops whatever StringBundle.prepare(java.util.Locale) loaded for locale: nothing reads it any more. Called by I18n when the process moves off a language no subtree retains, and when the last retain for a subtree language is released. A later prepare for the same locale must work again. Default: nothing, the right answer for a bundle that holds no per-locale state.
      Specified by:
      release in interface StringBundle

    • lookup

      public String lookup(String key, Locale locale)
      Description copied from interface: StringBundle
      The translation for key in locale, or null when this bundle does not have one. Called on the UI thread during measure and paint, so it must not block; see StringBundle.prepare(java.util.Locale).
      Specified by:
      lookup in interface StringBundle

    • toString

      public String toString()
      Overrides:
      toString in class Object