Class TranslationResult

java.lang.Object
com.lokalized.TranslationResult
@ThreadSafe public final class TranslationResult extends Object
Diagnostic result for a translation lookup. Instances are structurally immutable and safe to share. Collection state is defensively copied; an optional failure cause is exposed by reference and is outside this class's thread-safety guarantee.

If evaluating a reachable expression-fragment predicate or interpolating its selected/default fragment fails, a handler-produced result reports TranslationFailureReason.RESOLUTION_FAILURE and exposes the runtime cause. The default fallback policy stops at that failure, while TranslationFallbackPolicy.fallbackOnAnyFailure() may first try another locale. Expression-selected fragments have required defaults and therefore cannot themselves produce TranslationFailureReason.NO_MATCHING_ALTERNATIVE.

Since:
3.0.0
Author:
Mark Allen

  • Constructor Details

    • TranslationResult

      public TranslationResult(@NonNull String key, @NonNull String translation, @NonNull Locale lookupLocale, @Nullable Locale resolvedLocale, @NonNull List<@NonNull Locale> attemptedLocales, @NonNull TranslationResultStatus status, @Nullable TranslationFailureReason failureReason, @Nullable Throwable cause)
      Constructs a translation result. This is public so custom Strings implementations can participate in the diagnostic result API.
      Parameters:
      key - translation key, not null
      translation - returned string, not null
      lookupLocale - locale used to begin per-key locale fallback, not null
      resolvedLocale - successfully resolved locale, or null for a failure-handler response
      attemptedLocales - ordered locales actually attempted, not null
      status - result status, not null
      failureReason - final failure reason for a handler response, otherwise null
      cause - first runtime resolution cause, including an evaluated expression-fragment or selected/default fragment failure, otherwise null
      Throws:
      IllegalArgumentException - if any locale is malformed, success and failure state is mixed, a resolution cause and reason disagree, attempted locales contain duplicates, or the resolved locale was not attempted

    • TranslationResult

      public TranslationResult(@NonNull String key, @NonNull String translation, @NonNull Locale lookupLocale, @Nullable LocaleMatchResult localeMatchResult, @Nullable Locale resolvedLocale, @NonNull List<@NonNull Locale> attemptedLocales, @NonNull TranslationResultStatus status, @Nullable TranslationFailureReason failureReason, @Nullable Throwable cause)
      Constructs a translation result with locale-negotiation diagnostics.
      Parameters:
      key - translation key, not null
      translation - returned string, not null
      lookupLocale - locale used to begin per-key locale fallback, not null
      localeMatchResult - strict locale-negotiation result, or null when unavailable
      resolvedLocale - successfully resolved locale, or null for a failure-handler response
      attemptedLocales - ordered locales actually attempted, not null
      status - result status, not null
      failureReason - final failure reason for a handler response, otherwise null
      cause - runtime resolution cause, including an evaluated expression-fragment or selected/default fragment failure, otherwise null
      Throws:
      IllegalArgumentException - if any locale is malformed, success and failure state is mixed, a resolution cause and reason disagree, attempted locales contain duplicates, or the resolved locale was not attempted

  • Method Details

    • getKey

      public @NonNull String getKey()
      Gets the translation key.
      Returns:
      translation key, not null

    • getTranslation

      public @NonNull String getTranslation()
      Gets the returned translation, key, or handler-supplied string.
      Returns:
      returned translation, key, or handler-supplied string, not null

    • getLookupLocale

      public @NonNull Locale getLookupLocale()
      Gets the locale used to begin per-key locale fallback after any negotiation.
      Returns:
      locale used to begin per-key locale fallback after any negotiation, not null

    • getLocaleMatchResult

      public @NonNull Optional<@NonNull LocaleMatchResult> getLocaleMatchResult()
      Gets strict locale-negotiation diagnostics when available.
      Returns:
      strict locale-negotiation diagnostics when available, otherwise empty, not null

    • getResolvedLocale

      public @NonNull Optional<@NonNull Locale> getResolvedLocale()
      Gets the locale that resolved successfully.
      Returns:
      locale that resolved successfully, or empty for a failure response, not null

    • getAttemptedLocales

      public @NonNull List<@NonNull Locale> getAttemptedLocales()
      Gets the ordered locales actually attempted.
      Returns:
      ordered locales actually attempted, not null

    • getStatus

      public @NonNull TranslationResultStatus getStatus()
      Gets how the returned string was produced.
      Returns:
      how the returned string was produced, not null

    • getFailureReason

      public @NonNull Optional<@NonNull TranslationFailureReason> getFailureReason()
      Gets the final lookup failure reason for handler-produced results.

      Evaluated expression-fragment predicate and selected/default fragment failures are TranslationFailureReason.RESOLUTION_FAILURE; an expression-selected fragment cannot itself produce TranslationFailureReason.NO_MATCHING_ALTERNATIVE because it has a required default.

      Returns:
      final lookup failure reason for handler-produced results, otherwise empty, not null

    • getCause

      public @NonNull Optional<@NonNull Throwable> getCause()
      Gets the first runtime resolution cause for a failed lookup.
      Returns:
      first runtime resolution cause for a failed lookup, including an evaluated expression-fragment or selected/default fragment failure, otherwise empty, not null

    • isFallback

      public @NonNull Boolean isFallback()
      Reports whether negotiation or per-key resolution used a fallback.
      Returns:
      whether negotiation produced no match, used CLDR parent, likely-subtag, or primary-language fallback, or per-key resolution used a non-equivalent locale, not null

    • toString

      public @NonNull String toString()
      Generates a diagnostic representation without rendering translation contents or throwable messages.
      Overrides:
      toString in class Object
      Returns:
      a safe diagnostic representation, not null