edtf-humanize

edtf-humanize turns Extended Date/Time Format (EDTF) dates into human-readable strings, in English, French, German and Italian:

Date.edtf('1984~/2004-06').humanize # => "circa 1984 to June 2004"

It adds a humanize method to Date and to the EDTF::Century, EDTF::Decade, EDTF::Interval, EDTF::Season, EDTF::Set and EDTF::Unknown objects that the edtf-ruby gem parses. See edtf-ruby's documentation for the EDTF syntax it supports.

• Ruby 3.1 or later
• edtf 3.1 or later
• ActiveSupport 6.1 or later

On Ruby 4.0 with edtf 3.x, if nothing else in your bundle depends on racc (Rails apps usually get it through nokogiri), add gem 'racc' to your Gemfile. edtf 3.x needs it but doesn't declare it (inukshuk/edtf-ruby#50); edtf 4 declares it.

Add the gem to your Gemfile and run bundle install:

gem 'edtf-humanize'

Or install it directly with gem install edtf-humanize. Outside Rails, require it with:

require 'edtf-humanize'

Parse an EDTF string with Date.edtf and call humanize on the result.

A lowercase x and an uppercase X mean different things:

• 197x is a decade: the whole span, 1970 through 1979. edtf-ruby parses it as an EDTF::Decade (19xx as an EDTF::Century).
• 197X is one unknown year: a single year whose last digit isn't known. edtf-ruby parses it as a Date with an unspecified digit, so it renders as "1970s (year unknown)".

Output follows the current I18n.locale. The supported locales are :en, :fr, :de and :it:

Set the locale globally or for a block:

I18n.locale = :de
Date.edtf('1975-07-01').humanize # => "1. Juli 1975"

I18n.with_locale(:fr) { Date.edtf('1975-07-01').humanize } # => "1 Juillet 1975"

Setting any other locale raises I18n::InvalidLocale unless you provide translations for it (see Adding a language).

No extra setup is needed. require 'edtf-humanize' adds the gem's locale files to I18n.load_path:

require 'edtf-humanize'

I18n.locale = :it
Date.edtf('1975-22').humanize # => "estate 1975"

Require edtf-humanize, not edtf/humanize. The latter loads the code without the locale files, so setting a non-English locale raises I18n::InvalidLocale: :fr is not a valid locale.

Most wording comes from the I18n keys in config/locales. To change a term, add your own locale file to I18n.load_path after requiring the gem; later files take precedence:

# config/locales/my_overrides.en.yml
en:
  edtf:
    terms:
      approximate_date_prefix_year: "about "

I18n.load_path << 'config/locales/my_overrides.en.yml'
I18n.reload! # only needed if translations were already used

Date.edtf('1981~').humanize # => "about 1981"

Some language-specific wording, such as century names ("20th century", "XXe siècle"), is built in each language's module rather than read from I18n.

Pull requests adding languages are welcome. A new language needs:

• a module in lib/edtf/humanize/language/ that includes Edtf::Humanize::Language::Default and overrides what the language needs (see french.rb)
• a locale file in config/locales (see fr.edtf.yml)
• an entry for the locale in Configuration in lib/edtf/humanize.rb
• a spec file (see humanize_fr_spec.rb)

Tests use RSpec and style is enforced with RuboCop. Run both with:

bundle exec rake