Interface TranslationFailureHandler

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@ThreadSafe
@FunctionalInterface
public interface TranslationFailureHandler

Decides how Lokalized should respond when a localized string lookup fails after the configured TranslationFallbackPolicy stops fallback or all locale candidates are exhausted.

Failures from evaluating a reachable expression-fragment predicate or interpolating its selected/default fragment are reported as TranslationFailureReason.RESOLUTION_FAILURE. The default fallback policy stops on these failures, while TranslationFallbackPolicy.fallbackOnAnyFailure() may try another locale before invoking this handler. An expression-selected fragment always has a default translation, so its selection cannot itself produce TranslationFailureReason.NO_MATCHING_ALTERNATIVE.

Handlers shared by a Strings instance may be invoked concurrently and must be thread-safe.

Since:

3.0.0

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
@NonNull TranslationFailureResponse	handle(@NonNull TranslationFailure translationFailure)	Handles a failed localized string lookup.
static @NonNull TranslationFailureHandler	returnKey()	Returns the lookup key itself after interpolating supplied placeholders into it.
static @NonNull TranslationFailureHandler	returnKey(@NonNull Consumer<? super @NonNull TranslationFailure> observer)	Notifies an observer about each failed lookup and then returns the lookup key itself after interpolating supplied placeholders into it.
static @NonNull TranslationFailureHandler	throwException()	Throws an exception for failed lookups.

Method Details

handle

@NonNull TranslationFailureResponse handle(@NonNull TranslationFailure translationFailure)

Handles a failed localized string lookup.

Parameters:

translationFailure - the failed lookup, not null

Returns:

the response Lokalized should apply, not null

returnKey

static @NonNull TranslationFailureHandler returnKey()

Returns the lookup key itself after interpolating supplied placeholders into it.

Unmatched whole-message alternatives and runtime resolution failures are handled the same way as missing translations. This includes failures in evaluated expression-fragment predicates and selected/default fragments. Use throwException() or a custom handler that throws for TranslationFailureReason.RESOLUTION_FAILURE to surface broken generated-placeholder rules, expressions, interpolation, or custom resolvers.

Returns:

the handler, not null

returnKey

static @NonNull TranslationFailureHandler returnKey(@NonNull Consumer<? super @NonNull TranslationFailure> observer)

Notifies an observer about each failed lookup and then returns the lookup key itself after interpolating supplied placeholders into it.

Use TranslationFailure.getMessage() when the observer needs a message suitable for logging without exposing placeholder values. The observer may be invoked concurrently when the returned handler is shared by a Strings instance and must therefore be thread-safe. An exception thrown by the observer propagates to the caller.

Parameters:

observer - observer to notify before returning the key, not null

Returns:

the handler, not null

Since:

3.0.0

throwException

static @NonNull TranslationFailureHandler throwException()

Throws an exception for failed lookups.

A runtime cause supplied for TranslationFailureReason.RESOLUTION_FAILURE is rethrown. Other failure reasons produce a MissingTranslationException.

Returns:

the handler, not null