Roman2K / localized_dates forked from clemens/localized_dates

localized_dates

The localized_dates plugin takes away some of the pain of localizing dates and times. It leverages the power of the Rails i18n plugin to facilitate localization of dates and times.

Installation

To install the plugin, change into an existing Rails application and run:

  ruby script/plugin install git://github.com/Roman2K/localized_dates.git

This will download the plugin and store it in vendor/plugins/localized_dates.

Adding new formats

Adding new date and time formats is easy. Basic structure:

  en-US:
    date:
      formats:
        default:  "%Y-%m-%d"
        short:    "%e %b"
        long:     "%B %e, %Y"
        only_day: "%e"
    time:
      formats:
        default:      "%a %b %d %H:%M:%S %Z %Y"
        time:         "%H:%M"
        short:        "%d %b %H:%M"
        long:         "%B %d, %Y %H:%M"
        only_second:  "%S"
        datetime:
          formats:
            default: "%Y-%m-%dT%H:%M:%S%Z"
        am: 'am'
        pm: 'pm'

As you can see, there are two basic entities: date and time. time also has two children, datetime and time_with_zone that both inherit from time so you usually don’t even need to define them.

If you need more complex Ruby constructs such as lambdas, you still need to define them in a separate Ruby file. Take a look at the following example:

  {
    :'en-US' => {
      :date => {
        :formats => {
          :long_ordinal => lambda { |date| "%B #{date.day.ordinalize}, %Y" }
        }
      },
      :time => {
        :formats => {
          :long_ordinal => lambda { |time| "%B #{time.day.ordinalize}, %Y %H:%M" }
        },
        :time_with_zone => {
          :formats => {
            :default => lambda { |time| "%Y-%m-%d %H:%M:%S #{time.formatted_offset(false, 'UTC')}" }
          }
        }
      }
    }
  }

For example, if you define a time format named release_date, you can use Time.now.to_s(:release_date) in your views. You should always define a format named default for both date and time, that serves as the default format. You can use the default format by simply writing Time.now.to_s without passing any parameter.

You can either use a strftime compatible formatting string or a Proc that returns a strftime formatting string as a date/time format. Take a look at the following examples:

  :short => "%d %B, %H:%M" # => "03 August, 22:49"
  :long => lambda { |time| "%A, #{time.day}. %B %Y, %H:%M" } # => "Samstag, 3. August 2008, 22:49"

Please note that the use of Proc’s is slightly different from Rails’ original behavior:

  old: :long => lambda { |time| time.strftime("%A, #{time.day}. %B %Y, %H:%M") }
  new: :long => lambda { |time| "%A, #{time.day}. %B %Y, %H:%M" }

The old way should still work without throwing error messages, however, the dates and times will not be localized.

Further information on strftime formatting.

Customizing day and month names

If you localize your application for a language other than English, you most likely want to change the default month and day names to your own countries’ names. Here’s how it’s done:

  de-AT:
    date:
      day_names:        [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
      abbr_day_names:   [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
      month_names:      [~, January, February, March, April, May, June, July, August, September, October, November, December]
      abbr_month_names: [~, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
      order:            [:year, :month, :day]

The only caveat here is that month_names and abbr_month_names need nil as their respective first elements. If you don’t use nil as the first element you’ll end up with wrong dates (August will become September, etc.). Also note that the definition of day names starts with Sunday (not Monday).

Contributors

• Clemens Kofler (www.railway.at)
• Aslak Hellesøy (blog.aslakhellesoy.com/)
• Roman Le Négrate (roman.flucti.com)

Bugs, feedback and license

If you discover a bug or have positive feedback, Clemens Kofler would appreciate if you sent him an e-mail to clemens@railway.at. Please include a detailed description of your problem if you want him to help you.

Copyright © 2008 Clemens Kofler <clemens@railway.at>, released under the MIT license