B4A Library AHLocale library

With this library you can convert dates, timestamps, numbers and normal texts to the format your device uses. You can even translate your apps to different languages.

The AHLocale object provides many information about your devices locale settings like Currency symbol, month names, weekday names etc.

The AHTranslator object provides methods for creating multilanguage apps.

The AHDateTime object provides methods for formatting and parsing date strings. The internal DateTime object of B4A has the problem that it uses localized format identifier so it is not possible to parse a date string in the format "2011/05/19 12:15 AM" on a german device because the "AM" is "vorm." on it. With the AHDateTime object you can parse and format dates in any locale.

The AHTimeZone object provides methods to get information about timezones (like offset to UTC, DST offset etc.)

The AHDateUtils object provides methods to format dates and date ranges and display them localized.

The AHNumeric object provides methods to handle different (localized) number formats.

The example app starts always in english. Translation files for german, italian and japanese are provided. Try to select another language with the topmost spinner and see how the language of the user interface changes.

AHLocale
Author: Markus Stipp
Version: 1.16

• AHDateTime
  Fields:
  • DEFAULT As Int
  • FULL As Int
  • LONG As Int
  • MEDIUM As Int
  • SHORT As Int
  Methods:
  • Format (ticks As Long) As String
    Formats the specified ticks value to a string with the specified pattern.
  • GetDefaultDatePattern (Style As Int) As String
    Gets the default DatePattern of the device default locale
    
    Style - Use constants SHORT, MEDIUM, LONG, FULL, DEFAULT
  • GetDefaultDatePattern2 (Style As Int, Locale As AHLocale) As String
    Gets the default DatePattern of given locale
    
    Style - Use constants SHORT, MEDIUM, LONG, FULL, DEFAULT
    Locale - Reference to an AHLocale object
  • GetDefaultDateTimePattern (DateStyle As Int, TimeStyle As Int) As String
    Gets the device default DateTimePattern
    
    DateStyle - Style for Date
    TimeStyle - Style for Time
  • GetDefaultDateTimePattern2 (DateStyle As Int, TimeStyle As Int, Locale As AHLocale) As String
    Gets the DateTimePattern for the given Locale
    
    DateStyle - Style for Date
    TimeStyle - Style for Time
  • GetDefaultTimePattern (Style As Int) As String
    Gets the default TimePattern of the device default locale
    
    Style - Use constants SHORT, MEDIUM, LONG, FULL, DEFAULT
  • GetDefaultTimePattern2 (Style As Int, Locale As AHLocale) As String
    Gets the default TimePattern of given locale
    
    Style - Use constants SHORT, MEDIUM, LONG, FULL, DEFAULT
    Locale - Reference to an AHLocale object
  • GetShortDatePatternWithoutYear As String
    Return a short date pattern without year information
  • Initialize
    Initializes the AHDateTime object with the default locale.
  • Initialize2 (locale As AHLocale)
    Initializes the AHDateTime object with the given AHLocale object
  • InitializeUS
    Initializes the AHDateTime object with the <strong>en_US</strong> locale.
  • Parse (date As String) As Long
    Parses the specified string and returns a tick value.
    
    Throws an exception if the string can not be parsed.
  • is24HourFormat As Boolean
    Returns true if the user preference settings is 24 hour format.
  Properties:
  • Lenient As Boolean
    If you set this to true the parser is not very strict on his date format.
  • Pattern As String
    Sets or gets the Date/Time pattern
    
    Default pattern is: <strong>yyyy-MM-dd HH:mm:ss</strong>
    
    For allowed placeholders look here: <link>SimpleDateFormat|http://developer.android.com/reference/java/text/SimpleDateFormat.html</link>
  • TimeZone As AHTimezone
    Sets or gets the timezone for the AHDateTime object
• AHDateUtils
  Fields:
  • FORMAT_12HOUR As Int
  • FORMAT_24HOUR As Int
  • FORMAT_ABBREV_ALL As Int
  • FORMAT_ABBREV_MONTH As Int
  • FORMAT_ABBREV_RELIVE As Int
  • FORMAT_ABBREV_TIME As Int
  • FORMAT_ABBREV_WEEKDAY As Int
  • FORMAT_CAP_AMPM As Int
  • FORMAT_CAP_MIDNIGHT As Int
  • FORMAT_CAP_NOON As Int
  • FORMAT_CAP_NOON_MIDNIGHT As Int
  • FORMAT_NO_MIDNIGHT As Int
  • FORMAT_NO_MONTH_DAY As Int
  • FORMAT_NO_NOON As Int
  • FORMAT_NO_NOON_MIDNIGHT As Int
  • FORMAT_NO_YEAR As Int
  • FORMAT_NUMERIC_DATE As Int
  • FORMAT_SHOW_DATE As Int
  • FORMAT_SHOW_TIME As Int
  • FORMAT_SHOW_WEEKDAY As Int
  • FORMAT_SHOW_YEAR As Int
  • FORMAT_UTC As Int
  • LENGTH_LONG As Int
  • LENGTH_MEDIUM As Int
  • LENGTH_SHORT As Int
  • LENGTH_SHORTER As Int
  • LENGTH_SHORTEST As Int
  Methods:
  • FormatDateRange (StartTicks As Long, EndTicks As Long, Flags As Int) As String
    Formats a date or a time range according to the local conventions.
    
    Note that this is a convenience method. Using it involves creating an
    internal Formatter instance on-the-fly, which is somewhat costly in terms
    of memory and time.
    
    StartTicks - start time
    EndTicks - end time
    Flags - a bit mask of options
  • FormatDateTime (Ticks As Long, Flags As Int) As String
    Formats a date or a time according to the local conventions. There are
    lots of options that allow the caller to control, for example, if the
    time is shown, if the day of the week is shown, if the month name is
    abbreviated, if noon is shown instead of 12pm, and so on.
    
    Ticks - time/date to format
    Flags - a bit mask of options
  • FormatElapsedTime (Seconds As Long) As String
    Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on
    the call-in-progress screen.
    
    Seconds - the elapsed time in seconds.
  • GetRelativeDateTimeString (Ticks As Long, MinResolution As Long, TransitionResolution As Long, Flags As Int) As CharSequence
    Return string describing the elapsed time since startTime formatted like
    "[relative time/date], [time]".
    
    <b>Ticks</b> - some time in the past.
    
    <b>MinResolution</b> - the minimum elapsed time (in milliseconds) to
    report when showing relative times. For example, a time 3 seconds in the
    past will be reported as "0 minutes ago" if this is set to
    MINUTE_IN_MILLIS.
    
    <b>TransitionResolution</b> - the elapsed time (in milliseconds) at which
    to stop reporting relative measurements. Elapsed times greater than this
    resolution will default to normal date formatting. For example, will
    transition from "6 days ago" to "Dec 12" when using WEEK_IN_MILLIS.
    
    <b>Flags</b> - a bit mask of options
  • GetRelativeTimeSpanString (Ticks As Long, Now As Long, MinResolution As Long, Flags As Int) As CharSequence
    Returns a string describing 'time' as a time relative to 'now'.
    
    Time spans in the past are formatted like "42 minutes ago". Time spans in
    the future are formatted like "in 42 minutes". Can use
    FORMAT_ABBREV_RELATIVE flag to use abbreviated relative times, like
    "42 mins ago".
    
    <b>Ticks</b> - the time to describe, in milliseconds
    
    <b>Now</b> - the current time in
    milliseconds
    
    <b>MinResolution</b> - the minimum timespan to report. For example,
    a time 3 seconds in the past will be reported as "0 minutes ago" if this
    is set to MINUTE_IN_MILLIS. Pass one of 0, MINUTE_IN_MILLIS,
    HOUR_IN_MILLIS, DAY_IN_MILLIS, WEEK_IN_MILLIS
    
    <b>Flags</b> - a bit mask of
    formatting options, such as FORMAT_NUMERIC_DATE or FORMAT_ABBREV_RELATIVE
  • IsToday (Ticks As Long) As Boolean
    Returns true if the supplied Ticks value is today else false
• AHLocale
  Methods:
  • Initialize
    Initializes the AHLocale object with the default locale.
  • Initialize2 (language As String)
    Initializes the AHLocale object using the specified language.
  • Initialize3 (language As String, country As String)
    Initializes the AHLocale object using the specified language and country.
  • InitializeUS
    Initializes the AHLocale Object with <strong>en_US</strong> locale. This locale is
    available on every device.
  Properties:
  • AmPmStrings() As String [read only]
    Returns the array of strings which represent AM and PM.
  • AvailableLocales As List [read only]
    Returns the system's installed locales. These are returned as a B4A List of AHLocale Objects.
    There are only locales in this list which have a non empty country and language.
  • Country As String [read only]
    Returns the country/region code for this locale, which will either be the
    empty string or an uppercase ISO 3166 2-letter code.
  • CurrencyCode As String [read only]
    Returns this currency's ISO 4217 currency code.
  • CurrencyFractionDigits As Int [read only]
    Returns the default number of fraction digits for this currency.
  • CurrencySymbol As String [read only]
    Returns the localized currency symbol for this currency in locale.
  • DisplayCountry As String [read only]
    Returns the name of this locale's country, localized to locale. Returns
    the empty string if this locale does not correspond to a specific country
  • DisplayLanguage As String [read only]
    Returns the name of this locale's language, localized to locale. If the
    language name is unknown, the language code is returned.
  • DisplayName As String [read only]
    Returns this locale's language name, country name, and variant, localized
    to locale. The exact output form depends on whether this locale
    corresponds to a specific language, country and variant, such as:
    English, English (United States), English (United States,Computer),
    anglais (?tats-Unis), anglais (?tats-Unis,informatique).
  • EnglishCountry As String [read only]
    Returns the name of this locale's country in english. Returns
    the empty string if this locale does not correspond to a specific country
  • EnglishLanguage As String [read only]
    Returns the name of this locale's language in english. If the
    language name is unknown, the language code is returned.
  • EnglishName As String [read only]
    Returns this locale's language name, country name, and variant in english.
    The exact output form depends on whether this locale
    corresponds to a specific language, country and variant, such as:
    English, English (United States), English (United States,Computer),
    anglais (?tats-Unis), anglais (?tats-Unis,informatique).
  • FirstDayOfWeek As Int [read only]
    Gets the first day of the week
  • ISO3Country As String [read only]
    Gets the three letter ISO country code which corresponds to the country
    code for this Locale.
  • ISO3Language As String [read only]
    Gets the three letter ISO language code which corresponds to the language
    code for this Locale.
  • ISOCode As String [read only]
    Returns the ISO Code for this Locale such as <strong>en_US</strong> or <strong>de_DE</strong>
  • ISOCountries() As String [read only]
    Gets the list of two letter ISO country codes which can be used as the
    country code for a Locale.
  • ISOLanguages() As String [read only]
    Gets the list of two letter ISO language codes which can be used as the
    language code for a Locale.
  • Initialized As Boolean [read only]
    Returns if the object is initialized
  • Language As String [read only]
    Gets the language code for this Locale or the empty string if no language
    was set.
  • Months() As String [read only]
    Returns the array of strings containing the full names of the months.
  • ShortMonths() As String [read only]
    Returns the array of strings containing the abbreviated names of the months.
  • ShortWeekDays() As String [read only]
    Returns the array of strings containing the abbreviated names of the days of the week.
  • WeekDays() As String [read only]
    Returns the array of strings containing the full names of the days of the week.
• AHNumeric
  Methods:
  • Format (Value As Double) As String
    Format the number to a string using the pattern and rules of this object.
  • Initialize
    Initializes a standard NumberFormat object with the standard locale
  • Initialize2 (Locale As AHLocale)
    Initializes a standard NumberFormat object with the given locale.
  • InitializeCurrency
    Initializes a currency NumberFormat object with the standard locale
  • InitializeCurrency2 (Locale As AHLocale)
    Initializes a currency NumberFormat object with the given locale.
  • InitializeInteger
    Initializes an integer NumberFormat object with the standard locale
  • InitializeInteger2 (Locale As AHLocale)
    Initializes an integer NumberFormat object with the given locale.
  • InitializeNumber
    Initializes a standard NumberFormat object with the standard locale
  • InitializeNumber2 (Locale As AHLocale)
    Initializes a standard NumberFormat object with the given locale.
  • InitializePercent
    Initializes a percent NumberFormat object with the standard locale
  • InitializePercent2 (Locale As AHLocale)
    Initializes a percent NumberFormat object with the given locale.
  • Parse (Value As String) As Number
    Parse the given string and convert it to a number. This may throw a
    ParseException if the format of the string is not correct.
  Properties:
  • MaximumFractionDigits As Int
    Set or get the maximum fraction digits.
  • MaximumIntegerDigits As Int
    Set or get the maximum integer digits.
  • MinimumFractionDigits As Int
    Set or get the minimum fraction digits.
  • MinimumIntegerDigits As Int
    Set or get the minimum integer digits
  • Pattern As String
    Set or get the pattern that is used for formatting and parsing.
• AHTimeZone
  Fields:
  • STYLE_LONG As Int
  • STYLE_SHORT As Int
  Methods:
  • GetDisplayName (DaylightTime As Boolean, Style As Int) As String
    Returns the Display name of this timezone
    
    DaylightTime - Set to true if you want to have DST included into the name
    Style - AHTimeZone.SHORT or AHTimeZone.LONG format
  • GetDisplayName2 (DaylightTime As Boolean, Style As Int, Locale As AHLocale) As String
    Returns the Display name of this timezone
    
    DaylightTime - Set to true if you want to have DST included into the name
    Style - AHTimeZone.SHORT or AHTimeZone.LONG format
    Locale - a AHLocale object to set in which language you want the displayname
  • GetOffset (Date As Long) As Long
    Returns the offset in milliseconds from UTC for this time zone at time.
    The offset includes daylight savings time if the specified date is within the daylight savings time period.
    
    Date - Date for which you want to have the info
  • InDaylightTime (Date As Long) As Boolean
    Returns true if Date is in a daylight savings time period for this time zone.
    
    Date - Date for which you want to get the info
  • Initialize
    Initialize a AHTimeZone object with default timezone
  • Initialize2 (ID As String)
    Initializes a AHTimeZone object with the given TimeZone ID
    
    ID - TimeZone ID like "Europe/Berlin"
  Properties:
  • AvailableIds As List [read only]
    Returns a list of available timezone IDs on this device.
    One of the results can be passed to the Initialize2() Method to reinitialize
    an AHTimeZone object with a different timezone
  • DSTSavings As Long [read only]
    Returns the daylight savings offset in milliseconds for this time zone.
    The base implementation returns 3600000 (1 hour) for time zones that use daylight savings
    time and 0 for timezones that do not.
    Note that this method doesn't tell you whether or not to apply the offset: you need to call
    InDaylightTime() for the specific time you're interested in. If this method returns a non-zero
    offset, that only tells you that this TimeZone sometimes observes daylight savings.
  • ID As String
    Gets or sets the timezone ID as String for this timezone
  • RawOffset As Long
    Sets or gets the Raw offset for this timezone
• AHTranslator
  Methods:
  • GetText (text As String) As String
    Searches for the text in the translation table. If a translation is
    available it will be returned. If no translation is available the text is
    added to the missing translation table and the original text is returned.
    So you can write your whole program in a default language. If a
    translation is available it will be used, if not, the text will be
    returned in the default language.
  • GetText2 (text As String, params As List) As String
    Searches for the text in the translation table and returns the translated
    text.
    
    You can use Placeholders in the form of {1} {2} etc. which will be
    replaced with the content of the second parameter. {1} will be replaced
    with the first item in the Array/List, {2} with the second one and so on.
  • Initialize (dir As String, basename As String)
    Initializes a translation object with the device language. Tries to read a
    translation file with the following name convention: basename_language.lng
  • Initialize2 (dir As String, basename As String, language As String)
    Initializes a translation object with the given language. Tries to read a
    translation file with the following name convention: basename_language.lng
  • Initialize3 (dir As String, basename As String, language As String, country As String)
    Initializes a translation object with the given language and country code.
    Tries to read a translation file with the following name
    convention: basename_language_country.lng
  • WriteTranslation (dir As String, filename As String)
    Writes two files to the specified dir. The current translation Map is
    written to [filename]_[language].lng and the missing translation Map is
    written to [filename]_miss_[language].lng
  Properties:
  • CurrentCountry As String [read only]
    Returns the current County code
  • CurrentFile As String [read only]
    Returns current file name of language file
  • CurrentLanguage As String [read only]
    Returns current Language code
  • DefaultLanguage As String
    Sets or gets the default language. This is the language used when no language file is found.
    If you don't set it the default language will be empty and is not used.
  • Extension As String
    Sets or gets the current file extension
  • MissingTranslationMap As Map [read only]
    Returns a Map object with all text phrases which are missing in the
    translation file.
  • TranslationMap As Map
    Returns a Map object with the current translations

History:
V1.1:

• fixed Documentation
• fixed some bugs (DisplayXXX methods)
• new AHDateTime object
• some minor improvements

V1.11:

• fixed problem with AvailableLocales not working on all devices

V1.12:

• new AHTimeZone object to get information from timezones

V1.13: (never released)

• Add TimeZone property to AHDateTime object

V1.14:

• AHTranslator.java - Removed log output
• Timezone.java - fixed type

V1.15:

• AHDateUtils object - new
• AHNumeric object - new

V1.16:

• AHDateTime - Methods for getting default date and time format strings
• AHTranslation - Support for Countries
• AHTranslation - Support for default language
• AHTranslation - Support for different file extensions

 

[alwaysbusy]

Very usefull! Thank you

 

[moster67]

Very nice Markus. :icon_clap:

I just tried the example-project, changing the language on the emulator and then running your application and noted it works very well (for instance the variables from English into German and vice versa).

The AHLocale is also very useful to get local information about the device.

Thank you very much for this useful library. I hope Erel will put it online (of course with your permission) among the other libraries.

 

[moster67]

Marcus,

one question: in your German language-file I noted that you used:

u00DC

to get Ü

but I noted that if I wrote Ü directly in the file, it worked anyway.

I also tried with other characters such as ö å ä ò è and they all showed up correctly.

Do you suggest using Unicodes? (Unicode Escape I believe it is called)

PS: I added an Italian language-file and the application changed languages nicely between English, German and Italian according to the language set in the emulator. Nice job. Thanks!

 

[moster67]

I played again with the library and the language-file.

Just for fun, I tried Japanese although I don't know nothing about Japanese. I used the same words as in your example and then translated them into Japanese using Google-translation tools. I saved the file as UTF-8 using "ja" as the language-attribute in the file-name.

I set Japanese as language in the emulator. The application detects Japanese but it seems like the characters are not shown correctly. Do you know why this happens?

I attach an image and the exported zip-project. The Japanese language-file is in the Files-folder.

 

[Erel]

Great job. Thank you for sharing. Many users were waiting for these features.

I've uploaded the documentation: Basic4android - AHLocale

 

[alfcen]

Hi Moster67

I have tried it on my Japanese phone and it looks very much like in your emulator.

Also experimented with several encodings for the localeexample_ja file, SHIFT_JIS, JIS, EUC, UTF-8, however, without success. I need to get familiar with locale settings before I can do more.

 

[moster67]

Maybe we need to use Unicode Escape? I was looking for an online-converter but I coulnd't find one. I will try again tomorrow.

Hi Moster67

I have tried it on my Japanese phone and it looks very much like in your emulator.

Also experimented with several encodings for the localeexample_ja file, SHIFT_JIS, JIS, EUC, UTF-8, however, without success. I need to get familiar with locale settings before I can do more.

 

[corwin42]

I tried it yesterday with no success too. I even tried Unicode escape sequences with the same result.
One idea I haven't tried yet: Add a translation manually to the translation map using japanese weekdayname or monthname and write it to SD - card with file.writemap or trans.writetranslation to see what he generates.

 

[agraham]

Someone may have tried this but check that a phrase that does not display properly with the translator does display when directly added to a Label or EditText. If it then displays properly it is an encoding problem, if it does not then it is probably a font problem.

 

[moster67]

Good suggestion. I tried that by insering a label called myJapaneseLabel and then used the following code in the source-code:

myJapaneseLabel.Text="週の最初の曜日"

The Japanese characters are displayed correctly so I guess it is an encoding problem at this point.

Someone may have tried this but check that a phrase that does not display properly with the translator does display when directly added to a Label or EditText. If it then displays properly it is an encoding problem, if it does not then it is probably a font problem.

 

[moster67]

Marcus,

I don't know JAVA very well but I guess you are using map for storing data in your library. When you read the file, perhaps there is an option, when dealing with strings, how to deal with encoding.

In VB.net, I believe that with certain string-objects/methods you can set parameters as to the encoding. If I recall, you can tell it to use UTF-8. Maybe that is the way it must be done in JAVA as well?

Just some thoughts...

 

[agraham]

The library uses a Basic4android Map to store the language strings and uses File.ReadMap to populate it which in turn uses an instance of the Java Properties class and its load method. After a bit of Googling I think this is where the problem lies. The Android documentation doesn't mention it but the Java Platform SE 6 Properties class docs do say that, I assume for historical reasons, "This format uses the ISO 8859-1 character encoding".

I suspect this may have something to do with the problem as according to that documentation Unicode characters need special escaping to be represented in this format. The Properties.store method used by File.WriteMap might well do this but if you are using an external editor that writes UTF-8 to produce the language file I guess this is causing the problem.

 

[corwin42]

Andrew seems to be correct with ISO8859-1 character set. I converted all japanese characters to unicode escape sequences (Used this online converter)

After you convert all japanese characters to the unicode escape codes then everything seems to work.

 

[moster67]

Fantastic! Now it works! :sign0060:

Thank you very much Marcus and of course many thanks to Andrew as well for the hint to get it working.

Great job.

Edit: Oops. Did a mistake. Wait a moment. I think I have the solution.

Andrew seems to be correct with ISO8859-1 character set. I converted all japanese characters to unicode escape sequences (Used this online converter)

 

[corwin42]

Do you suggest using Unicodes? (Unicode Escape I believe it is called)

For japanese language: YES

I tried it yesterday with no success too. I even tried Unicode escape sequences with the same result.
One idea I haven't tried yet: Add a translation manually to the translation map using japanese weekdayname or monthname and write it to SD - card with file.writemap or trans.writetranslation to see what he generates.

:signOops:

Argh, I created a copy of the example project and edited the language files in the wrong folder. :BangHead:

But while searching for the problem I found some smaller bugs and some bad things in the documentation. I hope to find the time to fix all this very soon.

 

[corwin42]

Version 1.1 of this library is available in the first post.

Most interesting improvement is the AHDateTime object which provides methods for parsing and formatting dates. The difference to the builtin DateTime object is that the AHDateTime object can be used with any locale you want.

 

[bluedude]

Dropped this in my library folder but it says version 1. It does not have the AHDateTime object.

 

[corwin42]

Dropped this in my library folder but it says version 1. It does not have the AHDateTime object.

Should be the correct version in 1st post. Did you reload libraries in B4A?

 

[bluedude]

Version problem

corwin,

Still have the same problem after downloading the library, it says 1.00. See attached screenshot for prove.