io.sphere.sdk.models

Class LocalizedString

java.lang.Object

io.sphere.sdk.models.Base

io.sphere.sdk.models.LocalizedString

public final class LocalizedString
extends Base

A localized string is a object where the keys are Locales (HTTP API: ISO language tags), and the values are the corresponding strings used for that language.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food");

assertThat(ls.getTranslation(singletonList(Locale.US))).isEqualTo("dog food");//fuzzy search
assertThat(ls.getTranslation(singletonList(Locale.ENGLISH))).isEqualTo("dog food");//strict search
assertThat(ls.getLocales()).isEqualTo(new HashSet<>(asList(Locale.GERMAN, Locale.ENGLISH)));//inspecting locales
assertThat(ls.slugified())//slugified values for urls
        .isEqualTo(LocalizedString.of(Locale.GERMAN, "hundefutter", Locale.ENGLISH, "dog-food"));
final LocalizedString slugifiedUnique = ls.slugifiedUnique();
assertThat(slugifiedUnique.get(Locale.GERMAN)).matches("hundefutter-\\d+");//example: hundefutter-62899407
assertThat(slugifiedUnique.get(Locale.ENGLISH)).matches("dog-food-\\d+");
See the test code.

Method Summary

Modifier and Type	Method and Description
static LocalizedString	empty() Creates an instance without any value.
Optional<String>	find(Iterable<Locale> locales) Searches the translation for some exact locales in the order they appear and returning the result in an Optional.
Optional<String>	find(Locale locale) Searches the translation for an exact locale and returning the result in an Optional.
String	get(Iterable<Locale> locales) Searches the translation for some exact locales in the order they appear and using null as result if no match could be found.
String	get(Locale locale) Searches the translation for an exact locale by using null in the case the locale ist not present.
String	get(String languageTag) Searches the translation for a locale specified in IETF BCP 47 by language tag string.
Set<Locale>	getLocales() Returns all locales included in this instance.
String	getTranslation(Iterable<Locale> locales) Searches a translation which matches a locale in locales and uses language fallbackes.
LocalizedString	mapValue(BiFunction<Locale,String,String> function) Creates a new instance where each translation value is transformed with function.
static LocalizedString	of() Creates an instance without any value.
static LocalizedString	of(Locale locale, String value) Creates an instance with one locale translation pair.
static LocalizedString	of(Locale locale1, String value1, Locale locale2, String value2) Creates an instance for two different locales.
static LocalizedString	of(Map<Locale,String> translations) Creates an instance by supplying a map of Locale and String.
static LocalizedString	ofEnglish(String translationForEnglish)
static LocalizedString	ofStringToStringMap(Map<String,String> translations) Creates an instance by supplying a map of String the language tag and String.
LocalizedString	plus(Locale locale, String value) Creates a new LocalizedString containing the given entries and the new one.
LocalizedString	slugified() Creates a new LocalizedString where all translations are slugified (remove whitespace, etc.).
LocalizedString	slugifiedUnique() Creates a new LocalizedString where all translations are slugified (remove whitespace, etc.) and a random supplement is added.
Stream<LocalizedStringEntry>	stream() Creates a new Stream of entries.
static Collector<LocalizedStringEntry,?,LocalizedString>	streamCollector() Collector to collect a stream of LocalizedStringEntrys to one LocalizedString.
String	toString()
static com.fasterxml.jackson.core.type.TypeReference<LocalizedString>	typeReference() Creates a container which contains the full Java type information to deserialize this class from JSON.

Methods inherited from class io.sphere.sdk.models.Base

equals, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

of

public static LocalizedString of()

Creates an instance without any value.

Returns:

instance without any value

empty

public static LocalizedString empty()

Creates an instance without any value.

Returns:

instance without any value

of

public static LocalizedString of(Locale locale,
                                 String value)

Creates an instance with one locale translation pair.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter");
assertThat(ls.getLocales()).containsExactly(Locale.GERMAN);
assertThat(ls.get(Locale.GERMAN)).isEqualTo("Hundefutter");
assertThat(ls.get(Locale.ENGLISH)).isNull();
See the test code.

Parameters:

locale - the locale for the one translation

value - the translation for the specified locale

Returns:

translation for one language

of

public static LocalizedString of(Locale locale1,
                                 String value1,
                                 Locale locale2,
                                 String value2)

Creates an instance for two different locales.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food");
assertThat(ls.getLocales()).containsExactly(Locale.GERMAN, Locale.ENGLISH);
assertThat(ls.get(Locale.GERMAN)).isEqualTo("Hundefutter");
assertThat(ls.get(Locale.ENGLISH)).isEqualTo("dog food");
See the test code.

Parameters:

locale1 - the first locale

value1 - the translation corresponding to locale1

locale2 - the second locale which differs from locale1

value2 - the translation corresponding to locale2

Returns:

new instance for two key value pairs

of

public static LocalizedString of(Map<Locale,String> translations)

Creates an instance by supplying a map of Locale and String. Changes to the map won't affect the instance.

final Map<Locale, String> map = new HashMap<>();
map.put(Locale.GERMAN, "Hundefutter");
map.put(Locale.ENGLISH, "dog food");
final LocalizedString ls = LocalizedString.of(map);

assertThat(ls.getLocales()).containsExactly(Locale.GERMAN, Locale.ENGLISH);
assertThat(ls).isEqualTo(LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food"));

map.remove(Locale.GERMAN);
map.put(Locale.forLanguageTag("es"), "Comida para perro");

assertThat(ls.getLocales())
        .overridingErrorMessage("changes in the creation map do not change the created object")
        .containsExactly(Locale.GERMAN, Locale.ENGLISH);
assertThat(ls).isEqualTo(LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food"));
assertThat(ls.get(Locale.GERMAN)).isEqualTo("Hundefutter");
See the test code.

Parameters:

translations - the key value pairs for the translation

Returns:

a new instance which has the same key value pairs as translation at creation time

ofStringToStringMap

public static LocalizedString ofStringToStringMap(Map<String,String> translations)

Creates an instance by supplying a map of String the language tag and String. Changes to the map won't affect the instance.

final Map<String, String> map = new HashMap<>();
map.put("de", "Jacken");
map.put("en", "Jackets");
map.put("it", "Giacche");
final LocalizedString actual = LocalizedString.ofStringToStringMap(map);
final LocalizedString expected = LocalizedString
        .of(Locale.GERMAN, "Jacken")
        .plus(Locale.ENGLISH, "Jackets")
        .plus(Locale.ITALIAN, "Giacche");
assertThat(actual).isEqualTo(expected);
See the test code.

Parameters:

translations - the key value pairs for the translation

Returns:

a new instance which has the same key value pairs as translation at creation time

plus

public LocalizedString plus(Locale locale,
                            String value)

Creates a new LocalizedString containing the given entries and the new one. It is not allowed to override existing entries.

final LocalizedString singleGermanEntryLocalizedString = LocalizedString.of(Locale.GERMAN, "Hundefutter");

final LocalizedString twoEntriesLocalizedString = singleGermanEntryLocalizedString.plus(Locale.ENGLISH, "dog food");

assertThat(twoEntriesLocalizedString.get(Locale.GERMAN)).isEqualTo("Hundefutter");
assertThat(twoEntriesLocalizedString.get(Locale.ENGLISH)).isEqualTo("dog food");
assertThat(singleGermanEntryLocalizedString.get(Locale.GERMAN)).isEqualTo("Hundefutter");
assertThat(singleGermanEntryLocalizedString.get(Locale.ENGLISH))
        .overridingErrorMessage("the original instance did not change")
        .isNull();
assertThatThrownBy(() -> singleGermanEntryLocalizedString.plus(Locale.GERMAN, "override"))
        .isInstanceOf(IllegalArgumentException.class);
See the test code.

Parameters:

locale - the additional locale of the new entry

value - the value for the locale

Returns:

a LocalizedString containing this data and the from the parameters.

Throws:

IllegalArgumentException - if duplicate locales are provided

find

@Nonnull
public Optional<String> find(Locale locale)

Searches the translation for an exact locale and returning the result in an Optional.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter");

final Optional<String> germanTranslation = ls.find(Locale.GERMAN);
assertThat(germanTranslation).isEqualTo(Optional.of("Hundefutter"));

final Optional<String> englishTranslation = ls.find(Locale.ENGLISH);
assertThat(englishTranslation).isEqualTo(Optional.empty());
See the test code.

Parameters:

locale - the locale which should be searched

Returns:

A filled optional with the translation belonging to locale or an empty optional if the locale is not present.

get

@Nullable
public String get(Locale locale)

Searches the translation for an exact locale by using null in the case the locale ist not present.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter");

final String germanTranslation = ls.get(Locale.GERMAN);
assertThat(germanTranslation).isNotNull().isEqualTo("Hundefutter");

final String englishTranslation = ls.get(Locale.ENGLISH);
assertThat(englishTranslation).isNull();
See the test code.

Parameters:

locale - the locale which should be searched

Returns:

the translation belonging to locale or null if the locale is not present.

get

@Nullable
public String get(String languageTag)

Searches the translation for a locale specified in IETF BCP 47 by language tag string. If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored.

Parameters:

languageTag - the IETF language tag corresponding to an Locale

Returns:

the translation belonging to languageTag or null if the locale is not present.

find

@Nonnull
public Optional<String> find(Iterable<Locale> locales)

Searches the translation for some exact locales in the order they appear and returning the result in an Optional.

final LocalizedString ls = LocalizedString
        .of(Locale.GERMAN, "de")
        .plus(Locale.ENGLISH, "en")
        .plus(Locale.US, "en_US");

assertThat(ls.find(asList(Locale.US, Locale.ENGLISH))).isEqualTo(Optional.of("en_US"));
assertThat(ls.find(asList(Locale.FRENCH, Locale.ENGLISH))).isEqualTo(Optional.of("en"));
assertThat(ls.find(asList(Locale.UK, Locale.ENGLISH))).isEqualTo(Optional.of("en"));
assertThat(ls.find(asList(Locale.UK, Locale.GERMAN)))
        .overridingErrorMessage("no automatic fallback to plain English")
        .isEqualTo(Optional.of("de"));
assertThat(ls.find(asList(Locale.UK, Locale.CHINESE))).isEqualTo(Optional.empty());
See the test code.

Parameters:

locales - the locale which should be searched, the first exact match wins

Returns:

A filled optional with the translation belonging to one of the locales or an empty optional if none of the locales is not present.

get

@Nullable
public String get(Iterable<Locale> locales)

Searches the translation for some exact locales in the order they appear and using null as result if no match could be found.

final LocalizedString ls = LocalizedString
        .of(Locale.GERMAN, "de")
        .plus(Locale.ENGLISH, "en")
        .plus(Locale.US, "en_US");

assertThat(ls.get(asList(Locale.US, Locale.ENGLISH))).isEqualTo("en_US");
assertThat(ls.get(asList(Locale.FRENCH, Locale.ENGLISH))).isEqualTo("en");
assertThat(ls.get(asList(Locale.UK, Locale.ENGLISH))).isEqualTo("en");
assertThat(ls.get(asList(Locale.UK, Locale.GERMAN)))
        .overridingErrorMessage("no automatic fallback to plain English")
        .isEqualTo("de");
See the test code.

Parameters:

locales - the locale which should be searched, the first exact match wins

Returns:

the translation belonging to one of the locales or null if none of the locales is not present.

getTranslation

@Nullable
public String getTranslation(Iterable<Locale> locales)

Searches a translation which matches a locale in locales and uses language fallbackes. If locales which countries are used then the algorithm searches also for the pure language locale. So if "en_US" could not be found then "en" will be tried.

final LocalizedString ls = LocalizedString
        .of(Locale.GERMAN, "de")
        .plus(Locale.ENGLISH, "en")
        .plus(Locale.US, "en_US");

assertThat(ls.getTranslation(asList(Locale.US, Locale.ENGLISH))).isEqualTo("en_US");
assertThat(ls.getTranslation(asList(Locale.ENGLISH, Locale.US))).isEqualTo("en");
assertThat(ls.getTranslation(asList(Locale.FRENCH, Locale.ENGLISH))).isEqualTo("en");
assertThat(ls.getTranslation(asList(Locale.UK, Locale.ENGLISH))).isEqualTo("en");
assertThat(ls.getTranslation(asList(Locale.GERMAN, Locale.UK))).isEqualTo("de");
assertThat(ls.getTranslation(asList(Locale.UK, Locale.GERMAN)))
        .overridingErrorMessage(
                "the plain language fallback wins also in the case after that comes a concrete match")
        .isEqualTo("en");
assertThat(ls.getTranslation(asList(Locale.FRENCH, Locale.UK, Locale.GERMAN)))
        .overridingErrorMessage("automatic fallback to plain English")
        .isEqualTo("en");
assertThat(LocalizedString.of(Locale.US, "en_US").getTranslation(asList(Locale.ENGLISH)))
        .overridingErrorMessage("no fallback to locale with country")
        .isNull();

assertThat(ls.getTranslation(asList(Locale.UK, Locale.US, Locale.GERMAN)))
        .isEqualTo(ls.get(asList(Locale.UK, Locale.ENGLISH, Locale.US, Locale.ENGLISH, Locale.GERMAN)));

assertThat(ls.get("en"))
        .isEqualTo(ls.get(Locale.ENGLISH))
        .isEqualTo(ls.get("en-***")) //-*** is illegal (ietf bcp 47) and will be ignored
        .isNotEqualTo(ls.get(Locale.US));
assertThat(ls.get("de"))
        .isEqualTo(ls.get(Locale.GERMAN))
        .isNotEqualTo(ls.get("de-AT"));
assertThat(ls.get("en-US"))
        .isEqualTo(ls.get(Locale.US))
        .isEqualTo(ls.get("en-US-blub")) //-blub is illegal (ietf bcp 47) and will be ignored
        .isNotEqualTo(ls.get("en-US-u-islamcal")); //-u-islamcal legal extension (ietf bcp 47)
assertThat(ls.get("en_US"))
        .isNull();
assertThat(ls.get("xxx"))
        .isNull();
See the test code.

Parameters:

locales - the locales to try out

Returns:

a translation matching one of the locales or null

mapValue

public LocalizedString mapValue(BiFunction<Locale,String,String> function)

Creates a new instance where each translation value is transformed with function.

final LocalizedString upperCased = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food")
        .mapValue((locale, value) -> value.toUpperCase(locale));
assertThat(upperCased).isEqualTo(LocalizedString.of(Locale.GERMAN, "HUNDEFUTTER", Locale.ENGLISH, "DOG FOOD"));
See the test code.

Parameters:

function - transforms a value for a locale into a new value

Returns:

a new LocalizedString which consist all elements for this transformed with function

stream

public Stream<LocalizedStringEntry> stream()

Creates a new Stream of entries.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Company Hundefutter", Locale.ENGLISH, "Company dog food");

final Stream<LocalizedStringEntry> stream = ls.stream();

final LocalizedString updatedLs = stream
        .map(entry -> {
            final Locale locale = entry.getLocale();
            final String value = entry.getValue();
            final String newValue = value.replace("Company ", "");
            return LocalizedStringEntry.of(locale, newValue);
        })
        .collect(LocalizedString.streamCollector());
assertThat(updatedLs).isEqualTo(LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food"));
See the test code.

Returns:

stream of all entries

streamCollector

public static Collector<LocalizedStringEntry,?,LocalizedString> streamCollector()

Collector to collect a stream of LocalizedStringEntrys to one LocalizedString.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Company Hundefutter", Locale.ENGLISH, "Company dog food");

final Stream<LocalizedStringEntry> stream = ls.stream();

final LocalizedString updatedLs = stream
        .map(entry -> {
            final Locale locale = entry.getLocale();
            final String value = entry.getValue();
            final String newValue = value.replace("Company ", "");
            return LocalizedStringEntry.of(locale, newValue);
        })
        .collect(LocalizedString.streamCollector());
assertThat(updatedLs).isEqualTo(LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food"));
See the test code.

Returns:

collector

slugified

public LocalizedString slugified()

Creates a new LocalizedString where all translations are slugified (remove whitespace, etc.).

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food");
assertThat(ls.slugified())
        .isEqualTo(LocalizedString.of(Locale.GERMAN, "hundefutter", Locale.ENGLISH, "dog-food"));
See the test code.

Returns:

new instance

slugifiedUnique

public LocalizedString slugifiedUnique()

Creates a new LocalizedString where all translations are slugified (remove whitespace, etc.) and a random supplement is added. This slugify methods appends a random string for a little uniqueness.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food");

final LocalizedString slugifiedUnique = ls.slugifiedUnique();

assertThat(slugifiedUnique.get(Locale.GERMAN)).matches("hundefutter-\\d+");//example: hundefutter-62899407
assertThat(slugifiedUnique.get(Locale.ENGLISH)).matches("dog-food-\\d+");
See the test code.

Returns:

new instance

getLocales

@Nonnull
public Set<Locale> getLocales()

Returns all locales included in this instance.

final LocalizedString ls = LocalizedString.of(Locale.GERMAN, "Hundefutter", Locale.ENGLISH, "dog food");
final Set<Locale> locales = ls.getLocales();
assertThat(locales)
        .isEqualTo(new HashSet<>(asList(Locale.GERMAN, Locale.ENGLISH)));
See the test code.

Returns:

locales

toString

public String toString()

Overrides:

toString in class Base

typeReference

public static com.fasterxml.jackson.core.type.TypeReference<LocalizedString> typeReference()

Creates a container which contains the full Java type information to deserialize this class from JSON.

Returns:

type reference

See Also:

SphereJsonUtils.readObject(byte[], TypeReference), SphereJsonUtils.readObject(String, TypeReference), SphereJsonUtils.readObject(com.fasterxml.jackson.databind.JsonNode, TypeReference), SphereJsonUtils.readObjectFromResource(String, TypeReference)

ofEnglish

public static LocalizedString ofEnglish(String translationForEnglish)