diff --git a/HMCLCore/src/main/java/org/jackhuang/hmcl/util/i18n/LocalizedText.java b/HMCLCore/src/main/java/org/jackhuang/hmcl/util/i18n/LocalizedText.java index d98e82e44b..78e1d5ea53 100644 --- a/HMCLCore/src/main/java/org/jackhuang/hmcl/util/i18n/LocalizedText.java +++ b/HMCLCore/src/main/java/org/jackhuang/hmcl/util/i18n/LocalizedText.java @@ -23,28 +23,60 @@ import com.google.gson.annotations.JsonAdapter; import com.google.gson.stream.JsonReader; import com.google.gson.stream.JsonToken; import com.google.gson.stream.JsonWriter; -import org.jetbrains.annotations.NotNull; +import org.jackhuang.hmcl.util.gson.JsonSerializable; +import org.jetbrains.annotations.NotNullByDefault; import org.jetbrains.annotations.Nullable; import java.io.IOException; import java.util.*; +/// Represents text that may either be locale-independent or stored as values keyed by language tags. +/// +/// The JSON representation accepts either a string or an object. A string is treated as the same text for every +/// locale, while an object maps language keys, such as `en`, `zh-Hans`, or `default`, to localized text values. +/// +/// @author Glavo +@NotNullByDefault @JsonAdapter(LocalizedText.Adapter.class) +@JsonSerializable public final class LocalizedText { + /// Locale-independent text used when this instance is not backed by localized values. private final @Nullable String value; + + /// Text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)]. private final @Nullable Map localizedValues; - public LocalizedText(String value) { + /// Creates a locale-independent text value. + /// + /// When `value` is `null`, [#getText(List)] returns `null` for every candidate locale. + /// + /// @param value the text value, or `null` if the text is absent + public LocalizedText(@Nullable String value) { this.value = value; this.localizedValues = null; } - public LocalizedText(@NotNull Map localizedValues) { + /// Creates a localized text value backed by language-key mappings. + /// + /// The map is stored directly and is not copied. Later changes to `localizedValues` are visible through this + /// instance. + /// + /// @param localizedValues text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)] + /// @throws NullPointerException if `localizedValues` is `null` + public LocalizedText(Map localizedValues) { this.value = null; this.localizedValues = Objects.requireNonNull(localizedValues); } - public String getText(@NotNull List candidates) { + /// Returns the best matching text for the given candidate locales. + /// + /// If this instance stores localized values, the candidates are checked in iteration order after conversion with + /// [LocaleUtils#toLanguageKey(Locale)]. The first matching value is returned, or `null` if no candidate matches. + /// If this instance stores locale-independent text, the stored value is returned without checking `candidates`. + /// + /// @param candidates candidate locales ordered from most preferred to least preferred + /// @return the matched text, the locale-independent text, or `null` if no text is available + public @Nullable String getText(List candidates) { if (localizedValues != null) { for (Locale locale : candidates) { String value = localizedValues.get(LocaleUtils.toLanguageKey(locale)); @@ -56,10 +88,17 @@ public final class LocalizedText { return value; } + /// Gson adapter for the compact localized text JSON representation. static final class Adapter extends TypeAdapter { + /// Reads a localized text value from `null`, a JSON string, or a JSON object. + /// + /// @param jsonReader the reader positioned at the next localized text value + /// @return the parsed localized text, or `null` if the next JSON token is `null` + /// @throws IOException if reading from `jsonReader` fails + /// @throws JsonSyntaxException if the next token is neither `null`, a string, nor an object @Override - public LocalizedText read(JsonReader jsonReader) throws IOException { + public @Nullable LocalizedText read(JsonReader jsonReader) throws IOException { JsonToken nextToken = jsonReader.peek(); if (nextToken == JsonToken.NULL) { return null; @@ -83,8 +122,13 @@ public final class LocalizedText { } } + /// Writes a localized text value as `null`, a JSON string, or a JSON object. + /// + /// @param jsonWriter the writer that receives the JSON representation + /// @param localizedText the localized text to write, or `null` to write a JSON `null` + /// @throws IOException if writing to `jsonWriter` fails @Override - public void write(JsonWriter jsonWriter, LocalizedText localizedText) throws IOException { + public void write(JsonWriter jsonWriter, @Nullable LocalizedText localizedText) throws IOException { if (localizedText == null) { jsonWriter.nullValue(); } else if (localizedText.localizedValues != null) {