Class Strings.Builder

java.lang.Object
com.lokalized.Strings.Builder
Enclosing interface:
Strings
@NotThreadSafe public static class Strings.Builder extends Object
Builder used to construct Strings instances.

This class is intended for use by a single thread.

Since:
3.0.0
Author:
Mark Allen

  • Method Details

    • localizedStringSupplier

      public @NonNull Strings.Builder localizedStringSupplier(@Nullable Supplier<@NonNull Map<@NonNull Locale, ? extends @NonNull Iterable<@NonNull LocalizedString>>> localizedStringSupplier)
      Applies a localized string supplier to this builder.

      Locale keys returned by the supplier must be well-formed and must render to distinct IETF BCP 47 language tags. The returned map, its keys, each per-locale iterable, and every localized string must be non-null. Each per-locale iterable must contain unique translation keys.

      Parameters:
      localizedStringSupplier - localized string supplier, may be null
      Returns:
      this builder instance, useful for chaining. not null

    • localeSupplier

      public @NonNull Strings.Builder localeSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull Locale> localeSupplier)
      Applies a locale supplier to this builder.

      The supplier may be invoked concurrently after the Strings instance is built and must be thread-safe. It must return a well-formed IETF BCP 47 locale.

      Parameters:
      localeSupplier - locale supplier, may be null
      Returns:
      this builder instance, useful for chaining. not null

    • localeMatchSupplier

      public @NonNull Strings.Builder localeMatchSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull LocaleMatchResult> localeMatchSupplier)
      Applies a locale-negotiation-result supplier to this builder.

      Prefer this over localeSupplier(Function) when callers of Strings.getResult(String) should receive the original negotiation diagnostics. The supplier may be invoked concurrently and must be thread-safe. Supplying a non-null value replaces any locale supplier.

      Parameters:
      localeMatchSupplier - locale-match supplier, may be null
      Returns:
      this builder, not null
      Since:
      3.0.0

    • tiebreakerLocalesByLanguageCode

      public @NonNull Strings.Builder tiebreakerLocalesByLanguageCode(@Nullable Map<@NonNull String, @NonNull List<@NonNull Locale>> tiebreakerLocalesByLanguageCode)
      Applies a mapping of a well-formed IETF BCP 47 primary language subtag to its ordered "tiebreaker" fallback locales to this builder.

      Deprecated language aliases are canonicalized, so aliases such as he and iw must not both be supplied. Each list must be a duplicate-free exact permutation of the loaded Locales whose normalized primary language matches its key. This configuration is validated by build().

      Parameters:
      tiebreakerLocalesByLanguageCode - "tiebreaker" fallback locales, may be null; keys, lists, and locales must not be null
      Returns:
      this builder instance, useful for chaining. not null

    • phoneticResolver

      public @NonNull Strings.Builder phoneticResolver(@Nullable PhoneticResolver phoneticResolver)
      Applies a phonetic resolver to this builder.

      The resolver may be invoked concurrently after the Strings instance is built and must be thread-safe.

      Parameters:
      phoneticResolver - phonetic resolver, may be null (defaults to fail-fast resolver)
      Returns:
      this builder instance, useful for chaining. not null

    • translationFailureHandler

      public @NonNull Strings.Builder translationFailureHandler(@Nullable TranslationFailureHandler translationFailureHandler)
      Applies a translation failure handler to this builder.

      The handler may be invoked concurrently after the Strings instance is built and must be thread-safe.

      Parameters:
      translationFailureHandler - handler for failed lookups, may be null (defaults to returning the key)
      Returns:
      this builder instance, useful for chaining. not null

    • translationFallbackPolicy

      public @NonNull Strings.Builder translationFallbackPolicy(@Nullable TranslationFallbackPolicy translationFallbackPolicy)
      Applies the policy that decides whether failed locale attempts continue to fallback candidates.

      The policy may be invoked concurrently after the Strings instance is built and must be thread-safe. The default TranslationFallbackPolicy.fallbackOnMissingTranslationOrNoMatchingAlternative() policy stops on TranslationFailureReason.RESOLUTION_FAILURE, including failures while evaluating an expression-fragment predicate or interpolating its selected/default fragment.

      Parameters:
      translationFallbackPolicy - locale fallback policy, may be null to use the safe default
      Returns:
      this builder, not null

    • runtimeLimits

      public @NonNull Strings.Builder runtimeLimits(@Nullable TranslationRuntimeLimits runtimeLimits)
      Applies safety limits to localized strings construction and translation evaluation.

      Expression limits apply to both whole-message alternatives and expression-fragment alternatives. Generated-placeholder depth and expansion limits are shared by language-form and expression-selected fragments. The interpolated-output limit also bounds caller-supplied CharSequence values materialized for phonetic resolution.

      Parameters:
      runtimeLimits - runtime limits, may be null to use the library defaults
      Returns:
      this builder, not null
      Since:
      3.0.0

    • bidiIsolation

      public @NonNull Strings.Builder bidiIsolation(@Nullable BidiIsolation bidiIsolation)
      Applies bidirectional isolation behavior for caller-supplied placeholder values.

      Translation-owned text in generated fragments is not isolated; caller-supplied values interpolated into those fragments use this policy.

      Parameters:
      bidiIsolation - bidi isolation behavior, may be null (defaults to isolating caller-supplied values in RTL locales)
      Returns:
      this builder instance, useful for chaining. not null

    • build

      public @NonNull Strings build()
      Constructs a Strings instance.
      Returns:
      a Strings instance, not null
      Throws:
      IllegalArgumentException - if required localized-string or locale suppliers are missing, a configured locale is malformed, localized-string locale keys render to duplicate language tags, tiebreaker keys are invalid or collide after canonicalization, a tiebreaker list is not an exact permutation of its language's loaded locales, or supplied localized strings are invalid, including an alternative graph nested more than 128 levels deep
      ExpressionEvaluationException - if an expression cannot be compiled, including when it exceeds the configured runtime limits