Interface Strings

All Superinterfaces:
LocaleMatcher
public interface Strings extends LocaleMatcher
Contract for localized string providers - given a key and optional caller-supplied placeholders, return a localized string.

Format is "You are missing {{requiredFieldCount}} required fields."

Each lookup observes one unmodifiable shallow snapshot of the caller-supplied placeholder map. Whole-message alternative predicates, expression-fragment predicates, and language-form selectors read from that same snapshot for every locale candidate. Generated placeholder values do not become expression operands or language-form selector inputs; in particular, a language-form value or range endpoint always names raw caller input.

Generated-placeholder definitions declared by a LocalizedString are inherited along the selected whole-message alternative branch. The nearest selected descendant's complete definition replaces a same-named ancestor definition, unselected sibling definitions are invisible, and the resulting definition takes precedence over a same-named caller value when rendering output. Definitions are frozen for the selected branch before any generated fragment is resolved.

Author:
Mark Allen

  • Method Details

    • get

      @NonNull String get(@NonNull String key)
      Gets a localized string for the given key.

      If no localized string is available, the configured TranslationFailureHandler decides what happens.

      Parameters:
      key - the localization key, not null
      Returns:
      a localized string for the key, not null

    • get

      @NonNull String get(@NonNull String key, @NonNull TranslationOptions options)
      Gets a localized string for the given key and options.

      If no localized string is available, the configured or per-invocation TranslationFailureHandler decides what happens.

      Parameters:
      key - the localization key, not null
      options - per-invocation options, not null
      Returns:
      a localized string for the key, not null
      Since:
      3.0.0

    • get

      @NonNull String get(@NonNull String key, @Nullable Map<@NonNull String, @Nullable Object> placeholders)
      Gets a localized string for the given key.

      If no localized string is available, the configured TranslationFailureHandler decides what happens.

      Parameters:
      key - the localization key, not null
      placeholders - the placeholders to insert into the string, may be null
      Returns:
      a localized string for the key, not null

    • get

      @NonNull String get(@NonNull String key, @Nullable Map<@NonNull String, @Nullable Object> placeholders, @NonNull TranslationOptions options)
      Gets a localized string for the given key, placeholders, and options.

      If no localized string is available, the configured or per-invocation TranslationFailureHandler decides what happens.

      Parameters:
      key - the localization key, not null
      placeholders - the placeholders to insert into the string, may be null
      options - per-invocation options, not null
      Returns:
      a localized string for the key, not null
      Since:
      3.0.0

    • getResult

      default @NonNull TranslationResult getResult(@NonNull String key)
      Resolves a localized string and returns diagnostic information about the lookup.
      Parameters:
      key - localization key, not null
      Returns:
      translation result, not null
      Since:
      3.0.0

    • getResult

      default @NonNull TranslationResult getResult(@NonNull String key, @NonNull TranslationOptions options)
      Resolves a localized string with per-invocation options and returns diagnostic information.
      Parameters:
      key - localization key, not null
      options - per-invocation options, not null
      Returns:
      translation result, not null
      Since:
      3.0.0

    • getResult

      default @NonNull TranslationResult getResult(@NonNull String key, @Nullable Map<@NonNull String, @Nullable Object> placeholders)
      Resolves a localized string with placeholders and returns diagnostic information.
      Parameters:
      key - localization key, not null
      placeholders - caller-supplied placeholders, may be null
      Returns:
      translation result, not null
      Since:
      3.0.0

    • getResult

      @NonNull TranslationResult getResult(@NonNull String key, @Nullable Map<@NonNull String, @Nullable Object> placeholders, @NonNull TranslationOptions options)
      Resolves a localized string with placeholders and options and returns diagnostic information.

      A handler response that throws still throws; successful translations and return-key/return-string responses are represented by the returned result.

      The supplied map is shallow-copied once before the first locale candidate is attempted. Alternative predicates, language-form selectors, failure reporting, and every fallback candidate observe that same snapshot. Generated fragments are resolved separately and cannot change expression operands or selector inputs.

      Parameters:
      key - localization key, not null
      placeholders - caller-supplied placeholders, may be null
      options - per-invocation options, not null
      Returns:
      translation result, not null
      Since:
      3.0.0

    • getSupportedLocales

      @NonNull Set<@NonNull Locale> getSupportedLocales()
      Gets the locales for which localized strings were supplied.
      Returns:
      the supported locales, not null
      Since:
      3.0.0

    • getKeysForLocale

      @NonNull Set<@NonNull String> getKeysForLocale(@NonNull Locale locale)
      Gets the localized string keys supplied for the given locale.
      Parameters:
      locale - locale to inspect, not null
      Returns:
      the localized string keys for the locale, not null
      Throws:
      IllegalArgumentException - if the locale is not supported
      Since:
      3.0.0

    • getMissingKeys

      @NonNull Set<@NonNull String> getMissingKeys(@NonNull Locale sourceLocale, @NonNull Locale targetLocale)
      Gets the keys supplied by sourceLocale but missing from targetLocale.
      Parameters:
      sourceLocale - locale whose keys are used as the source set, not null
      targetLocale - locale whose keys are compared against the source set, not null
      Returns:
      keys present in sourceLocale and missing from targetLocale, not null
      Throws:
      IllegalArgumentException - if either locale is not supported
      Since:
      3.0.0

    • withFallbackLocale

      static @NonNull Strings.Builder withFallbackLocale(@NonNull Locale fallbackLocale)
      Vends a Strings instance builder for the specified fallback locale. 
      Strings strings = Strings.withFallbackLocale(Locale.forLanguageTag("en"))
    .localizedStringSupplier(() -> LocalizedStringLoader.loadFromClasspath("strings"))
    .localeSupplier((matcher) -> matcher.bestMatchFor(Locale.forLanguageTag("en-GB")))
    .build();
      Parameters:
      fallbackLocale - the fallback locale, not null
      Returns:
      a builder for a Strings instance, not null
      Throws:
      IllegalArgumentException - if the fallback locale is not a well-formed IETF BCP 47 locale