NLS (Sirius Kernel 2.12 API)

java.lang.Object
- sirius.kernel.nls.NLS

```
public class NLS
extends Object
```
Native Language Support used by the framework.
This class provides a translation engine (get(String), safeGet(String, String, String), fmtr(String)). It also provides access to the current language via getCurrentLang() and to the default language (getDefaultLanguage(). Most of the methods come in two versions, one which accepts a lang parameter and another which uses the currently active language.
Additionally this class provides conversion methods to and from String. The most prominent ones are toUserString(Object) and toMachineString(Object) along with their equivalent parse methods. Although some conversions, especially toMachineString or formatSize are not language dependent, those are kept in this class, to keep all conversion methods together.
Babelfish is used as translation engine and responsible for loading all provided .properties files.
Configuration
- nls.defaultLanguage: Sets the two-letter code used as default language
- nls.language: Sets an array of two-letter codes which enumerate all supported languages
See Also:

Babelfish

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NLS.CommonKeys
Provides access to commonly used keys.

Nested Classes
Modifier and Type	Class and Description
`static class`	`NLS.CommonKeys` Provides access to commonly used keys.

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static String`	`apply(String key, Object... params)` Deprecated. As it can be easily confused with `Strings.apply(String, Object...)`. Also using `fmtr(String)` is strongly encouraged.
`static String`	`convertDuration(long duration)` Converts the given duration in milliseconds including seconds and milliseconds This is a boilerplate method for `convertDuration(long, boolean, boolean)` with `includeSeconds` and `includeMillis` set to `true`.
`static String`	`convertDuration(long duration, boolean includeSeconds, boolean includeMillis)` Converts a given time range in milliseconds to a human readable format using the current language
`static Formatter`	`fmtr(String property)` Creates a formatted using the pattern supplied by the translation value for the given `property`.
`static Formatter`	`fmtr(String property, String lang)` Creates a formatted using the pattern supplied by the translation value for the given `property`.
`static String`	`formatSize(long size)` Converts a file or byte size.
`static String`	`get(String property)` Returns a translated text for the given `property` and the currently active language.
`static String`	`get(String property, String lang)` Returns a translated text for the given property in the given language.
`static String`	`getCurrentLang()` Returns the currently active language as two-letter code.
`static java.time.format.DateTimeFormatter`	`getDateFormat(String lang)` Returns the date format for the given language.
`static java.time.format.DateTimeFormatter`	`getDateTimeFormat(String lang)` Returns the date and time format (without seconds) for the given language.
`static String`	`getDayOfWeek(int day)` Converts a given integer (`Calendar.Monday...Calendar.Sunday`) into textual their representation.
`static String`	`getDayOfWeekShort(int day)` Returns a two letter abbreviation of the name of the given day, like `"Mo"`.
`static NumberFormat`	`getDecimalFormat()` Returns the format for the current language to format decimal numbers
`static NumberFormat`	`getDecimalFormat(String lang)` Returns the format for the given language to format decimal numbers
`static DecimalFormatSymbols`	`getDecimalFormatSymbols()` Returns the decimal format symbols for the current language
`static DecimalFormatSymbols`	`getDecimalFormatSymbols(String lang)` Returns the decimal format symbols for the given language
`static String`	`getDefaultLanguage()` Returns the two-letter code of the default language.
`static Optional<String>`	`getIfExists(String property, String lang)` Returns a translated text for the given `property` in the given language or `null` if no translation was found.
`static String`	`getMonthName(int month)` Returns the name of the given month in the current language
`static String`	`getMonthNameShort(int month)` Returns a three letter abbreviation of the name of the given month, like `"Jan"`.
`static Set<String>`	`getSupportedLanguages()` Returns a list of two-letter codes enumerating all supported languages.
`static String`	`getSystemLanguage()` Returns the two-letter code of the system language.
`static java.time.format.DateTimeFormatter`	`getTimeFormat(String lang)` Returns the time format (without seconds) for the given language.
`static java.time.format.DateTimeFormatter`	`getTimeFormatWithSeconds(String lang)` Returns the full time format (with seconds) for the given language.
`static java.time.format.DateTimeFormatter`	`getTimeParseFormat(String lang)` Returns the time format which is intended to parse time value in the given language.
`static Babelfish`	`getTranslationEngine()` Provides direct access to the translation engine to supply new properties or inspect current ones.
`static void`	`init(Classpath classpath)` Initializes the engine based on the given classpath
`static boolean`	`isSupportedLanguage(String twoLetterLanguageCode)` Determines if the given language code is supported or not.
`static String`	`makeLang(String lang)` Checks if the given language is supproted.
`static String`	`nonNLS(String s)` Marks a string as deliberately not translated.
`static <V> V`	`parseMachineString(Class<V> clazz, String value)` Parses the given string by expecting a machine independent format.
`static <V> V`	`parseUserString(Class<V> clazz, String string)` Parses the given string by expecting a format as defined by the current language.
`static <V> V`	`parseUserString(Class<V> clazz, String value, String lang)` Parses the given string by expecting a format as defined by the given language.
`static String`	`safeGet(String property, String fallback)` Returns a translated text for the given `property` or for the given `fallback`, if no translation for `property` was found.
`static String`	`safeGet(String property, String fallback, String lang)` Returns a translated text for the given `property` or for the given `fallback`, if no translation for `property` was found.
`static void`	`setDefaultLanguage(String lang)` Overrides the default language as defined in the configuration (`nls.defaultLanguage`).
`static String`	`smartRound(double number)` Outputs integer numbers without decimals, but fractional numbers with two digits.
`static void`	`startMonitoring(Classpath classpath)` Start the monitoring of resources in development environments.
`static String`	`toEnglishRepresentation(Number number)` Returns a string representation of the given number in an english format, that is, using a dot as decimal separator.
`static String`	`toMachineString(Object data)` Formats the given data in a language independent format.
`static String`	`toSpokenDate(java.time.temporal.Temporal date)` Converts dates to a "human" (e.g.
`static String`	`toUserString(Object object)` Formats the given data according to the format rules of the current language
`static String`	`toUserString(Object data, String lang)` Formats the given data according to the format rules of the given language

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getCurrentLang
```
@Nonnull
public static String getCurrentLang()
```
    Returns the currently active language as two-letter code.
    
    Returns:
    
    a two-letter code of the currently active language, as defined in CallContext.getLang()
  - getDefaultLanguage
```
@Nonnull
public static String getDefaultLanguage()
```
    Returns the two-letter code of the default language. Provided via the config in nls.defaultLanguage
    If this is set to "auto" the default language will be the system language.
    
    Returns:
    
    the language code of the default language
  - setDefaultLanguage
```
public static void setDefaultLanguage(String lang)
```
    Overrides the default language as defined in the configuration (nls.defaultLanguage).
    This can be used to enforce the system language. However, setting nls.defaultLanguage to 'auto' is the recommended approach.
    
    Parameters:
    
    lang - the two letter language code to use as default language.
    
    See Also:
    
    getSystemLanguage()
  - getSystemLanguage
```
@Nullable
public static String getSystemLanguage()
```
    Returns the two-letter code of the system language.
    By default, SIRIUS initializes with the language set in nls.defaultLanguage so a switchover to the system language has to be performed manually.
    
    Returns:
    
    the language code of the underlying operating system. If the language is not supported (not listed in nls.languages), null will be returned as CallContext.setLang(String) doesn't change the current language if null is passed in.
  - getSupportedLanguages
```
public static Set<String> getSupportedLanguages()
```
    Returns a list of two-letter codes enumerating all supported languages. Provided via the config in nls.languages
    
    Returns:
    
    a list of supported language codes
  - isSupportedLanguage
```
public static boolean isSupportedLanguage(String twoLetterLanguageCode)
```
    Determines if the given language code is supported or not.
    
    Parameters:
    
    twoLetterLanguageCode - the language as two-letter code
    
    Returns:
    
    true if the language is listed in nls.languages, false otherwise.
  - makeLang
```
@Nullable
public static String makeLang(@Nullable
                                        String lang)
```
    Checks if the given language is supproted. Returns the default language otherwise.
    Note that if the given lang is empty or null, this method will also return null as a call to CallContext.setLang(String) with null as parameter won't change the language at all.
    
    Parameters:
    
    lang - the language to check
    
    Returns:
    
    lang if it was a supported language or the defaultLanguage otherwise, unless an empty string was passed in, in which case null is returned.
  - init
```
public static void init(Classpath classpath)
```
    Initializes the engine based on the given classpath
    
    Parameters:
    
    classpath - the classpath used to discover all .properties files
  - startMonitoring
```
public static void startMonitoring(Classpath classpath)
```
    Start the monitoring of resources in development environments.
    
    Parameters:
    
    classpath - the classpath used to resolve .properties files
  - getTranslationEngine
```
public static Babelfish getTranslationEngine()
```
    Provides direct access to the translation engine to supply new properties or inspect current ones.
    
    Returns:
    
    the internally used translation engine
  - get
```
public static String get(@Nonnull
                         String property)
```
    Returns a translated text for the given property and the currently active language.
    If no translation is found, the translation for the default language is used. If still no translation is found, the property itself is returned.
    
    Parameters:
    
    property - the key for which a translation is requested
    
    Returns:
    
    a translated string for the current language (or for the default language if no translation was found) or the property itself if no translation for neither of both languages is available.
  - get
```
public static String get(@Nonnull
                         String property,
                         @Nullable
                         String lang)
```
    Returns a translated text for the given property in the given language.
    The same fallback rules as for get(String) apply.
    
    Parameters:
    
    property - the key for which a translation is requested
    
    lang - a two-letter language code for which the translation is requested
    
    Returns:
    
    a translated string in the requested language or a fallback value if no translation was found
  - getIfExists
```
public static Optional<String> getIfExists(@Nonnull
                                           String property,
                                           @Nullable
                                           String lang)
```
    Returns a translated text for the given property in the given language or null if no translation was found.
    The same fallback rules as for get(String, String) apply. However, if no translation
    
    Parameters:
    
    property - the key for which a translation is requested
    
    lang - a two-letter language code for which the translation is requested
    
    Returns:
    
    a translated text in the requested language (or in the default language if no translation for the given language was found). Returns an empty optional if no translation for this property exists at all.
  - safeGet
```
public static String safeGet(@Nonnull
                             String property,
                             @Nonnull
                             String fallback,
                             @Nullable
                             String lang)
```
    Returns a translated text for the given property or for the given fallback, if no translation for property was found.
    
    Parameters:
    
    property - the primary key for which a translation is requested
    
    fallback - the fallback key for which a translation is requested
    
    lang - a two-letter language code for which the translation is requested
    
    Returns:
    
    a translated text in the requested language for the given property, or for the given fallback. If either of both doesn't provide a translation for the given language, the translation for the default language is returned. If neither of both keys exist property will be returned.
  - safeGet
```
public static String safeGet(@Nonnull
                             String property,
                             @Nonnull
                             String fallback)
```
    Returns a translated text for the given property or for the given fallback, if no translation for property was found.
    
    Parameters:
    
    property - the primary key for which a translation is requested
    
    fallback - the fallback key for which a translation is requested
    
    Returns:
    
    a translated text in the current language for the given property, or for the given fallback. If either of both doesn't provide a translation for the given language, the translation for the default language is returned. If neither of both keys exist property will be returned.
  - fmtr
```
public static Formatter fmtr(@Nonnull
                             String property)
```
    Creates a formatted using the pattern supplied by the translation value for the given property.
    
    Parameters:
    
    property - the property to used to retrieve a translated pattern
    
    Returns:
    
    a Formatter initialized with the translated text of the given property
  - fmtr
```
public static Formatter fmtr(@Nonnull
                             String property,
                             @Nullable
                             String lang)
```
    Creates a formatted using the pattern supplied by the translation value for the given property.
    
    Parameters:
    
    property - the property to used to retrieve a translated pattern
    
    lang - a two-letter language code for which the translation is requested
    
    Returns:
    
    a Formatter initialized with the translated text of the given property
  - apply
```
@Deprecated
public static String apply(String key,
                                       Object... params)
```
    Deprecated. As it can be easily confused with Strings.apply(String, Object...). Also using fmtr(String) is strongly encouraged.
    
    Formats a translated string by replacing templates with the given parameters.
    Uses the same format as Strings.apply(String, Object...). However, this method should only be used for very simple strings. fmtr(String) provides support for named parameters, which are easier to translate.
    
    Parameters:
    
    key - the key used to lookup the translated text
    
    params - parameters used to replace arguments
    
    Returns:
    
    a translated and formatted string as defined in Strings.apply
  - nonNLS
```
public static String nonNLS(String s)
```
    Marks a string as deliberately not translated.
    Can be used to signal that a string needs no internationalization as it is only used on rare cases etc.
    
    Parameters:
    
    s - the text which will be used as output
    
    Returns:
    
    the given value for s
  - getDayOfWeek
```
public static String getDayOfWeek(int day)
```
    Converts a given integer (Calendar.Monday...Calendar.Sunday) into textual their representation.
    
    Parameters:
    
    day - the weekday to be translated. Use constants Calendar.MONDAY etc.
    
    Returns:
    
    the name of the given weekday in the current language or "" if an invalid index was given
  - getDayOfWeekShort
```
public static String getDayOfWeekShort(int day)
```
    Returns a two letter abbreviation of the name of the given day, like "Mo".
    
    Parameters:
    
    day - the weekday to be translated. Use constants Calendar.MONDAY etc.
    
    Returns:
    
    returns the first two letters of the name or "" if the given index was invalid.
  - getMonthName
```
public static String getMonthName(int month)
```
    Returns the name of the given month in the current language
    
    Parameters:
    
    month - the month which name is requested (1..12)
    
    Returns:
    
    the name of the given month translated in the current language or "" if an invalid index was given
  - getMonthNameShort
```
public static String getMonthNameShort(int month)
```
    Returns a three letter abbreviation of the name of the given month, like "Jan".
    
    Parameters:
    
    month - the month to be translated (January is 1, December is 12).
    
    Returns:
    
    returns the first three letters of the name or "" if the given index was invalid.
  - getDateFormat
```
public static java.time.format.DateTimeFormatter getDateFormat(String lang)
```
    Returns the date format for the given language.
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getTimeFormatWithSeconds
```
public static java.time.format.DateTimeFormatter getTimeFormatWithSeconds(String lang)
```
    Returns the full time format (with seconds) for the given language.
    This should be used to format dates (times). Use getTimeParseFormat(String) to parse strings as it is more reluctant (or use parseUserString(Class, String)).
    The pattern in this case will conform to the PHP 5 patterns as these are used by some JavaScript libraries like jQuery timepicker. (See http://php.net/manual/en/function.date.php).
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getTimeFormat
```
public static java.time.format.DateTimeFormatter getTimeFormat(String lang)
```
    Returns the time format (without seconds) for the given language.
    This should be used to format dates (times). Use getTimeParseFormat(String) to parse strings as it is more reluctant (or use parseUserString(Class, String)).
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getTimeParseFormat
```
public static java.time.format.DateTimeFormatter getTimeParseFormat(String lang)
```
    Returns the time format which is intended to parse time value in the given language.
    In contrast to getTimeFormat(String) and getTimeFormatWithSeconds(String) this is used to parse dates and is more reluctant when it comes to formatting (parses '9:00' whereas getTimeFormat(String) only accepts '09:00').
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getDateTimeFormat
```
public static java.time.format.DateTimeFormatter getDateTimeFormat(String lang)
```
    Returns the date and time format (without seconds) for the given language.
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getDecimalFormat
```
public static NumberFormat getDecimalFormat()
```
    Returns the format for the current language to format decimal numbers
    
    Returns:
    
    a format initialized with the pattern described by the current language
  - getDecimalFormat
```
public static NumberFormat getDecimalFormat(String lang)
```
    Returns the format for the given language to format decimal numbers
    
    Parameters:
    
    lang - the language for which the format is requested
    
    Returns:
    
    a format initialized with the pattern described by the given language
  - getDecimalFormatSymbols
```
public static DecimalFormatSymbols getDecimalFormatSymbols()
```
    Returns the decimal format symbols for the current language
    
    Returns:
    
    the decimal format symbols like thousands separator or decimal separator as described by the current language
  - getDecimalFormatSymbols
```
public static DecimalFormatSymbols getDecimalFormatSymbols(String lang)
```
    Returns the decimal format symbols for the given language
    
    Parameters:
    
    lang - the two-letter code of the language for which the decimal format symbols should be returned
    
    Returns:
    
    the decimal format symbols like thousands separator or decimal separator as described by the given language
  - toMachineString
```
public static String toMachineString(Object data)
```
    Formats the given data in a language independent format.
    
    Parameters:
    
    data - the input data which should be converted to string
    
    Returns:
    
    string representation of the given object, which can be parsed by parseMachineString(Class, String) independently of the language settings
  - toEnglishRepresentation
```
public static String toEnglishRepresentation(Number number)
```
    Returns a string representation of the given number in an english format, that is, using a dot as decimal separator.
    
    Parameters:
    
    number - the number to be converted
    
    Returns:
    
    a string representation of the given number using a dot as decimal separator independent of the current language settings
  - toUserString
```
public static String toUserString(Object object)
```
    Formats the given data according to the format rules of the current language
    
    Parameters:
    
    object - the object to be converted to a string
    
    Returns:
    
    a string representation of the given object, formatted by the language settings of the current language
  - toUserString
```
public static String toUserString(Object data,
                                  String lang)
```
    Formats the given data according to the format rules of the given language
    
    Parameters:
    
    data - the object to be converted to a string
    
    lang - a two-letter language code for which the translation is requested
    
    Returns:
    
    a string representation of the given object, formatted by the language settings of the current language
  - toSpokenDate
```
public static String toSpokenDate(java.time.temporal.Temporal date)
```
    Converts dates to a "human" (e.g. "today", "yesterday") format.
    The following texts are supported:
    - If the given date contains a time and is less than 30 min ago: "some minutes ago"
    - If the given date contains a time and is less than 60 min ago: "N minutes ago"
    - If the given date contains a time and is less than 2 hours ago: "one hour ago"
    - If the given date contains a time and is less than 6 hours ago: "N hours ago"
    - If the given date is today: "today"
    - If the given date is tomorrow: "tomorrow"
    - If the given date is yesterday: "yesterday"
    - For everything else we use the date format (note that in this case the time is omitted
    Parameters:
    
    date - the date to be formatted
    
    Returns:
    
    a date string which a human would use in common sentences
  - parseMachineString
```
public static <V> V parseMachineString(Class<V> clazz,
                                       String value)
```
    Parses the given string by expecting a machine independent format.
    This can parse all strings generated by toMachineString
    
    Type Parameters:
    
    V - the target type be be parsed
    
    Parameters:
    
    clazz - the expected class of the value to be parsed
    
    value - the string to be parsed
    
    Returns:
    
    an instance of clazz representing the parsed string or null if value was empty.
    
    Throws:
    
    IllegalArgumentException - if the given input was not well formed or if instances of clazz cannot be created. The thrown exception has a translated error message which can be directly presented to the user.
  - parseUserString
```
public static <V> V parseUserString(Class<V> clazz,
                                    String value,
                                    String lang)
```
    Parses the given string by expecting a format as defined by the given language.
    
    Type Parameters:
    
    V - the target type be be parsed
    
    Parameters:
    
    clazz - the expected class of the value to be parsed
    
    value - the string to be parsed
    
    lang - the two-letter code of the language which format should be used
    
    Returns:
    
    an instance of clazz representing the parsed string or null if value was empty.
    
    Throws:
    
    IllegalArgumentException - if the given input was not well formed or if instances of clazz cannot be created. The thrown exception has a translated error message which can be directly presented to the user.
  - parseUserString
```
public static <V> V parseUserString(Class<V> clazz,
                                    String string)
```
    Parses the given string by expecting a format as defined by the current language.
    
    Type Parameters:
    
    V - the target type be be parsed
    
    Parameters:
    
    clazz - the expected class of the value to be parsed
    
    string - the string to be parsed
    
    Returns:
    
    an instance of clazz representing the parsed string or null if value was empty.
    
    Throws:
    
    IllegalArgumentException - if the given input was not well formed or if instances of clazz cannot be created. The thrown exception has a translated error message which can be directly presented to the user.
  - convertDuration
```
public static String convertDuration(long duration,
                                     boolean includeSeconds,
                                     boolean includeMillis)
```
    Converts a given time range in milliseconds to a human readable format using the current language
    
    Parameters:
    
    duration - the duration in milliseconds
    
    includeSeconds - determines whether to include seconds or to ignore everything below minutes
    
    includeMillis - determines whether to include milli seconds or to ignore everything below seconds
    
    Returns:
    
    a string representation of the given duration in days, hours, minutes and, if enabled, seconds and milliseconds
  - convertDuration
```
public static String convertDuration(long duration)
```
    Converts the given duration in milliseconds including seconds and milliseconds
    This is a boilerplate method for convertDuration(long, boolean, boolean) with includeSeconds and includeMillis set to true.
    
    Parameters:
    
    duration - the duration in milliseconds
    
    Returns:
    
    a string representation of the given duration in days, hours, minutes, seconds and milliseconds
  - smartRound
```
public static String smartRound(double number)
```
    Outputs integer numbers without decimals, but fractional numbers with two digits.
    Discards fractional parts which absolute value is less or equal to 0.00001.
    
    Parameters:
    
    number - the number to be rounded
    
    Returns:
    
    a string representation using the current languages decimal format. Rounds fractional parts less or equal to 0.00001
  - formatSize
```
public static String formatSize(long size)
```
    Converts a file or byte size.
    Supports sizes up to petabyte. Uses conventional abbreviations like KB, MB but technically returns KiB or MiB (this is values divided by 1024 instead of 1000).
    
    Parameters:
    
    size - the size to format in bytes
    
    Returns:
    
    an english representation (using dot as decimal separator) along with one of the known abbreviations: Bytes, KB, MB, GB, TB, PB.

Class NLS

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getCurrentLang

getDefaultLanguage

setDefaultLanguage

getSystemLanguage

getSupportedLanguages

isSupportedLanguage

makeLang

init

startMonitoring

getTranslationEngine

get

get

getIfExists

safeGet

safeGet

fmtr

fmtr

apply

nonNLS

getDayOfWeek

getDayOfWeekShort

getMonthName

getMonthNameShort

getDateFormat

getTimeFormatWithSeconds

getTimeFormat

getTimeParseFormat

getDateTimeFormat

getDecimalFormat

getDecimalFormat

getDecimalFormatSymbols

getDecimalFormatSymbols

toMachineString

toEnglishRepresentation

toUserString

toUserString

toSpokenDate

parseMachineString

parseUserString

parseUserString

convertDuration

convertDuration

smartRound

formatSize