dotiw 5.5.0 → 5.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32864f97b3b06dc77f8c793e11a5b17b1d2af506bdfac0c559354f3e4eef7998
-  data.tar.gz: 20efed42fb0802a836f078f2791d78e7b863005b73780243ad4867bbf653103e
+  metadata.gz: fa29e6fb27292383b6c52e90e638a79df342e512d2132fc43399fbdac2accce7
+  data.tar.gz: a2a5f6a9f954ffa985ecb48a5888f860191be892e451f5a25726d9c7e7bb58d2
 SHA512:
-  metadata.gz: 6bb97a0d7bc860b57432dc81cb3d8a7921c6364c5271db648d30984164f26d6f4003e21de28252f958294960df1b0270cc4fbf83ae7602be23096829404ee2fe
-  data.tar.gz: e2d4f70428937b7e5c409666612dd7aefbe63e71d884a3738b240c222fc2f36a8df7a66b83fa4d52fef96cd27e7edd3a9fdecb15e497fa46853e9b3922f83663
+  metadata.gz: d95cc6198e93afadd8a16b09125166a1b0a8474c21f44cb194ae1e77e0a1cfa2a1e35c2a752bf275b16c7d0ec54144d99c3a2940865db373f80d0b3668c77a39
+  data.tar.gz: 00cdcea3f7f60fed460de3992568f7bce85c680212cac766a55a2186782fa9e76d578326f4af29bee6dc877fd614fb875ed5430e9288be18209be0ac17638155

data/.github/workflows/ruby.yml

@@ -9,26 +9,33 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - ruby-version: 3.4
-          - ruby-version: 3.3
-          - ruby-version: 3.2
-          - ruby-version: 3.1
-          - ruby-version: 3.0
-          - ruby-version: 2.7
-          - ruby-version: 2.7
+          - ruby-version: '4.0'
+          - ruby-version: '3.4'
+          - ruby-version: '3.3'
+          - ruby-version: '3.2'
+          - ruby-version: '3.1'
+          - ruby-version: '3.0'
+          - ruby-version: '2.7'
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.0.gemfile
-          - ruby-version: 2.7
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.1.gemfile
-          - ruby-version: 2.7
+          - ruby-version: '2.7'
             gemfile: gemfiles/rails_5.2.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_6.0.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.0.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.1.gemfile
-          - ruby-version: 3.4
+          - ruby-version: '3.4'
             gemfile: gemfiles/rails_7.2.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.0.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.1.gemfile
+          - ruby-version: '3.4'
+            gemfile: gemfiles/rails_8.1_i18n.gemfile
     steps:
       - uses: actions/checkout@v2
       - name: Set up Ruby
@@ -44,3 +51,20 @@ jobs:
           gem install bundler -v ${BUNDLER:-2.1.4}
           bundle install --jobs 4 --retry 3
           bundle exec rake
+      - name: Upload coverage to Coveralls
+        if: matrix.ruby-version == '3.4'
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: ruby-${{ matrix.ruby-version }}-${{ matrix.gemfile }}
+          parallel: true
+
+  finish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Close parallel build
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true

data/.gitignore

@@ -1,5 +1,6 @@
 tmp
 pkg
+coverage
 spec/fixtures/database.yml
 .rvmrc
 Gemfile.lock

data/Appraisals

@@ -25,3 +25,16 @@ end
 appraise 'rails_7.2' do
   gem 'rails', '~> 7.2.0'
 end
+
+appraise 'rails_8.0' do
+  gem 'rails', '~> 8.0.0'
+end
+
+appraise 'rails_8.1' do
+  gem 'rails', '~> 8.1.0'
+end
+
+appraise 'rails_8.1_i18n' do
+  gem 'rails', '~> 8.1.0'
+  gem 'rails-i18n'
+end

data/CHANGELOG.md

@@ -1,12 +1,35 @@
-## 5.4.0 (Next)
+## 5.6.1 (2026/09/09)
+
+* [#160](https://github.com/radar/distance_of_time_in_words/issues/160): Fix `offset_delta` incorrectly folding the full UTC offset difference into the distance when comparing timestamps with different, unrelated offsets (e.g. one in UTC, one with an explicit `-08:00` offset) instead of only when they're the same clock across a real DST/tzdata transition - [@dblock](https://github.com/dblock).
+* [#162](https://github.com/radar/distance_of_time_in_words/issues/162): Fix `same_clock?` incorrectly treating two `Time` values converted from `ActiveSupport::TimeWithZone` in different zones as the same clock on Rails >= 8.0, where `#to_time` returns a `Time` whose `#zone` is the `ActiveSupport::TimeZone` object itself rather than a `nil`/String abbreviation - [@dblock](https://github.com/dblock).
+* [#165](https://github.com/radar/distance_of_time_in_words/issues/165): Fix `offset_delta` folding the full UTC offset change into the top-level distance, which could overcorrect past zero and report "less than 1 second" for a case where a small real elapsed time (e.g. 1 minute) crosses a much larger DST transition (e.g. Europe/Dublin's 1 hour fall-back) - the offset correction is now only applied to the sub-day leftover once the distance has already been split into calendar fields - [@dblock](https://github.com/dblock).
+* [#170](https://github.com/radar/distance_of_time_in_words/issues/170): Fix `distance_of_time_in_words` unnecessarily converting an `ActiveSupport::TimeWithZone` argument to a plain `Time` via `#to_time`, which discarded its real zone on Rails < 8.0 and prevented `same_clock?` from correctly folding in a historical UTC offset change (e.g. Pacific/Norfolk's 2015 offset change, #153) on those versions - [@dblock](https://github.com/dblock).
+
+## 5.6.0 (2026/08/28)
+
+* [#145](https://github.com/radar/distance_of_time_in_words/pull/145): Add `dotiw/core` require path to use dotiw without overriding the Rails date helpers, `DOTIW.distance_of_time_in_words` shortcut - [@ermolaev](https://github.com/ermolaev).
+* [#146](https://github.com/radar/distance_of_time_in_words/pull/146): Add support for Rails 8 - [@dblock](https://github.com/dblock).
+* [#147](https://github.com/radar/distance_of_time_in_words/pull/147): Add support for Rails 8.1, drop the `tzinfo ~> 1.2.7` development pin - [@ermolaev](https://github.com/ermolaev).
+* [#148](https://github.com/radar/distance_of_time_in_words/pull/148): Add `max_unit` option to express the entire distance as a single number in one unit - [@dblock](https://github.com/dblock).
+* [#79](https://github.com/radar/distance_of_time_in_words/issues/79): Speed up `distance_of_time_in_words` by avoiding `I18n.with_options`/`ActiveSupport::OptionMerger` allocation for translations, using `I18n.translate` directly instead - [@dblock](https://github.com/dblock).
+* [#77](https://github.com/radar/distance_of_time_in_words/issues/77), [#120](https://github.com/radar/distance_of_time_in_words/issues/120): Fix `only`/`except` discarding the duration of excluded fractions instead of folding them into the next smaller included fraction - [@dblock](https://github.com/dblock).
+* [#63](https://github.com/radar/distance_of_time_in_words/issues/63): Fix incorrect DST correction in timezones with an inverted DST scheme (e.g. Europe/Dublin) by comparing `utc_offset` instead of the unreliable `Time#dst?` - [@dblock](https://github.com/dblock).
+* [#153](https://github.com/radar/distance_of_time_in_words/issues/153): Fix leftover hours/minutes leaking a historical UTC offset change (e.g. Pacific/Norfolk's 2015 offset change) into the result instead of folding it into the calendar distance - [@dblock](https://github.com/dblock).
+* [#44](https://github.com/radar/distance_of_time_in_words/issues/44): Document that `vague: true` combined with a non-English `locale:` requires the host application to load Rails' own translations for that locale - [@dblock](https://github.com/dblock).
+* [#156](https://github.com/radar/distance_of_time_in_words/pull/156): Add Ruby 4.0 to the test matrix - [@dblock](https://github.com/dblock).
+* [#158](https://github.com/radar/distance_of_time_in_words/pull/158): Add test coverage reporting with SimpleCov and Coveralls, merged across all Ruby 3.4 CI jobs (default + pinned Rails gemfiles) using parallel builds - [@dblock](https://github.com/dblock).
+
+## 5.5.0 (2026/03/15)
 
 * [#131](https://github.com/radar/distance_of_time_in_words/pull/131): Deprecates `highest_measure_only`. Adds alternate form of `highest_measures` option to permit rounding up whatever part of the duration was previously silently discarded - [@seansfkelley](https://github.com/seansfkelley).
 * [#133](https://github.com/radar/distance_of_time_in_words/pull/133): Test on Ruby 3.0 and 3.1 - [@dblock](https://github.com/dblock).
 * [#134](https://github.com/radar/distance_of_time_in_words/pull/134): Add support for Dzongkha, the National language of Bhutan - [@KinWang-2013](https://github.com/KinWang-2013).
 * [#135](https://github.com/radar/distance_of_time_in_words/pull/135): Add support for Ruby 2.7 and 3.2, removed support for ruby 2.4, 2.5, 2.6 and Rails 4 - [@KinWang-2013](https://github.com/KinWang-2013).
 * [#136](https://github.com/radar/distance_of_time_in_words/pull/136): Add support for Rails 7 - [@KinWang-2013](https://github.com/KinWang-2013).
-* [#139](https://github.com/radar/distance_of_time_in_words/pull/139): Fix bug with pluralization of Russian translations for numbers ending in 1 - [bitberry-dev](https://github.com/bitberry-dev).
-* Your contribution here.
+* [#139](https://github.com/radar/distance_of_time_in_words/pull/139): Fix bug with pluralization of Russian translations for numbers ending in 1 - [@bitberry-dev](https://github.com/bitberry-dev).
+* [#140](https://github.com/radar/distance_of_time_in_words/pull/140): Add Ruby 3.3 and 3.4 support, added logger - [@dblock](https://github.com/dblock).
+* [#141](https://github.com/radar/distance_of_time_in_words/pull/141): Fix flaky time calculation test by explicitly setting timezone - [@bitberry-dev](https://github.com/bitberry-dev).
+* Fix bug when accumulating on years - [@radar](https://github.com/radar).
 
 ## 5.3.3 (2022/04/25)
 

data/README.markdown

@@ -1,4 +1,4 @@
-# dotiw ![Ruby](https://github.com/radar/distance_of_time_in_words/workflows/Ruby/badge.svg)
+# dotiw ![Ruby](https://github.com/radar/distance_of_time_in_words/workflows/Ruby/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/radar/distance_of_time_in_words/badge.svg?branch=master)](https://coveralls.io/github/radar/distance_of_time_in_words?branch=master)
 
 The `dotiw` library that adds `distance_of_time_in_words` to any Ruby project, or overrides the default implementation in Rails with more accurate output.
 
@@ -32,6 +32,23 @@ include ActionView::Helpers::TextHelper
 include ActionView::Helpers::NumberHelper
 ```
 
+### Rails, without overriding the built-in helpers
+
+Requiring `dotiw` replaces the Rails implementation of `distance_of_time_in_words`
+and `time_ago_in_words`. If you would rather keep the built-in Rails helpers and
+call dotiw explicitly, require `dotiw/core` instead:
+
+```ruby
+gem 'dotiw', require: 'dotiw/core'
+```
+
+This loads `DOTIW::Methods` and the dotiw translations, but leaves
+`ActionView::Helpers::DateHelper` untouched:
+
+```ruby
+DOTIW.distance_of_time_in_words(from_time, to_time, highest_measures: 1)
+```
+
 ## distance\_of\_time\_in\_words
 
 Take this for a totally kick-ass example:
@@ -117,6 +134,8 @@ This will also be passed to `to_sentence`.
 
 Specify this if you want it to use the old `distance_of_time_in_words`. The value can be anything except `nil` or `false`.
 
+Note that `:vague` falls back to Rails/ActionView's own `distance_of_time_in_words`, which looks up its translations under `datetime.distance_in_words`. This namespace is provided by Rails core translations (e.g. via the [rails-i18n](https://github.com/svenfuchs/rails-i18n) gem) for non-English locales, not by dotiw. If you combine `:vague` with a non-English `:locale` and see a "translation missing" error, make sure your application also loads the corresponding Rails translations for that locale (see [#44](https://github.com/radar/distance_of_time_in_words/issues/44)).
+
 #### :include_seconds
 
 As described above this option is the equivalent to the third argument whether to include seconds.
@@ -130,38 +149,67 @@ Specifies the maximum output unit which will accumulate all the surplus. Say you
 => "121 minutes and 10 seconds"
 ```
 
+Note that units below `accumulate_on` are still shown separately. If you want the entire distance expressed as a single number in one unit, use `:max_unit` instead.
+
+#### :max_unit
+
+Expresses the entire distance as a single number in the given unit, discarding (flooring) any remainder smaller than that unit. Unlike `:accumulate_on`, no other units are shown in the output.
+
+```ruby
+>> distance_of_time_in_words(Time.now, Time.now + 1.day, true, max_unit: :seconds)
+=> "86400 seconds"
+
+>> distance_of_time_in_words(Time.now, Time.now + 3.days + 2.hours, true, max_unit: :hours)
+=> "74 hours"
+
+>> distance_of_time_in_words_hash(Time.now, Time.now + 3.days + 2.hours, max_unit: :hours)
+=> {hours: 74}
+```
+
+Valid units are `:seconds`, `:minutes`, `:hours`, `:days`, `:weeks`, `:months` and `:years`.
+
 #### :only
 
 Only want a specific measurement of time? No problem!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.minute, false, only: :minutes)
-=> "1 minute"
+=> "61 minutes"
 ```
 
+Excluded measurements are folded into the next smaller included measurement instead of being
+discarded, so the returned duration is always accurate (1 hour + 1 minute = 61 minutes, not 1
+minute).
+
 You only want some? No problem too!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.day + 1.minute, false, only: [:minutes, :hours])
-=> "1 hour and 1 minute"
+=> "25 hours and 1 minute"
 ```
 
+Here the excluded day is folded into hours (1 day + 1 hour = 25 hours).
+
 #### :except
 
 Don't want a measurement of time? No problem!
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.minute, false, except: :minutes)
-=> "1 hour"
+=> "1 hour and 60 seconds"
 ```
 
+The excluded minute is folded into seconds (1 minute = 60 seconds) rather than discarded.
+
 Culling a whole group of measurements of time:
 
 ```ruby
 >> distance_of_time_in_words(Time.now, Time.now + 1.hour + 1.day + 1.minute, false, except: [:minutes, :hours])
-=> "1 day"
+=> "1 day and 3660 seconds"
 ```
 
+The excluded hour and minute cascade down into seconds (1 hour + 1 minute = 3660 seconds).
+
 #### :highest\_measure\_only
 
 > **Deprecated**. Use `highest_measures: 1` instead.

data/RELEASING.md

@@ -0,0 +1,71 @@
+# Releasing DOTIW
+
+There are no hard rules about when to release dotiw. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+
+## Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [GitHub Actions](https://github.com/radar/distance_of_time_in_words/actions) for all supported platforms.
+
+Add a date to this release in [CHANGELOG.md](CHANGELOG.md).
+
+```
+## 5.5.1 (2026/03/28)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/dotiw/version.rb
+git commit -m "Preparing for release, 5.5.1."
+git push origin master
+```
+
+Release.
+
+```
+rake release
+```
+
+This builds the gem, creates and pushes a git tag, and pushes the gem to [RubyGems](https://rubygems.org/gems/dotiw).
+
+```
+dotiw 5.5.1 built to pkg/dotiw-5.5.1.gem.
+Tagged v5.5.1.
+Pushed git commits and tags.
+Pushed dotiw 5.5.1 to rubygems.org.
+```
+
+Create a GitHub release for the tag using the `gh` CLI, passing the CHANGELOG entries for this version as the release notes.
+
+```
+gh release create v5.5.1 --title "5.5.1" --notes "$(sed -n '/^## 5.5.1/,/^## /p' CHANGELOG.md | sed '$d')"
+```
+
+## Prepare for the Next Version
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+## 5.5.2 (Next)
+
+* Your contribution here.
+```
+
+Increment the patch version number in [lib/dotiw/version.rb](lib/dotiw/version.rb).
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/dotiw/version.rb
+git commit -m "Preparing for next developer iteration, 5.5.2."
+git push origin master
+```

data/benchmarks/distance_of_time_in_words_bench.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Benchmark for https://github.com/radar/distance_of_time_in_words/issues/79
+#
+# Compares dotiw's distance_of_time_in_words against Rails' original
+# ActionView::Helpers::DateHelper#distance_of_time_in_words, using the
+# scenario from the issue and its follow-up comments.
+#
+# Run with `ruby benchmarks/distance_of_time_in_words_bench.rb` after
+# `gem install benchmark-ips benchmark-memory actionview`.
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'benchmark/ips'
+require 'benchmark/memory'
+
+require_relative '../lib/dotiw'
+
+begin
+  require 'action_view'
+rescue LoadError
+  warn "This benchmark requires actionview: gem install actionview"
+  exit 1
+end
+
+include ActionView::Helpers::DateHelper
+
+now = Time.now
+future_time = Time.now + 100.years + 30.days + 50.seconds
+
+%i[ips memory].each do |type|
+  Benchmark.public_send(type) do |x|
+    x.report('dotiw') { DOTIW.distance_of_time_in_words(now, future_time) }
+    x.report('rails') { distance_of_time_in_words(now, future_time, include_seconds: true) }
+
+    x.compare!
+  end
+end

data/dotiw.gemspec

@@ -26,10 +26,10 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'pry'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec', '~> 3.0'
-  s.add_development_dependency 'tzinfo', '~> 1.2.7'
   s.add_development_dependency 'mutex_m'
   s.add_development_dependency 'base64'
   s.add_development_dependency 'bigdecimal'
+  s.add_development_dependency 'simplecov'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.0.0'
+gem 'tzinfo', '~> 2.0'
+
+
+gemspec path: '../'

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.1.0'
+gem 'tzinfo', '~> 2.0'
+
+
+gemspec path: '../'

data/gemfiles/rails_8.1_i18n.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '~> 8.1.0'
+gem 'rails-i18n'
+gem 'tzinfo', '~> 2.0'
+
+gemspec path: '../'

data/lib/dotiw/core.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'i18n'
+require 'logger'
+require 'active_support'
+require 'active_support/core_ext'
+
+module DOTIW
+  extend ActiveSupport::Autoload
+
+  eager_autoload do
+    autoload :VERSION, 'dotiw/version'
+    autoload :TimeHash, 'dotiw/time_hash'
+    autoload :Methods, 'dotiw/methods'
+  end
+
+  extend self
+
+  DEFAULT_I18N_SCOPE = :'datetime.dotiw'
+  DEFAULT_I18N_SCOPE_COMPACT = :'datetime.dotiw_compact'
+
+  # DOTIW.distance_of_time_in_words(...), DOTIW.time_ago_in_words(...), etc.
+  extend Methods
+
+  def init_i18n!
+    I18n.load_path.unshift(*locale_files)
+    I18n.reload!
+  end
+
+  def languages
+    @languages ||= (locale_files.map { |path| path.split(%r{[/.]})[-2].to_sym })
+  end
+
+  def locale_files
+    files 'locale', '*.yml'
+  end
+
+  protected
+
+  def files(directory, ext)
+    Dir[File.join File.dirname(__FILE__), directory, ext]
+  end
+end
+
+DOTIW.init_i18n!

data/lib/dotiw/methods.rb

@@ -5,8 +5,8 @@ module DOTIW
     extend self
 
     def distance_of_time_in_words_hash(from_time, to_time, options = {})
-      from_time = from_time.to_time if !from_time.is_a?(Time) && from_time.respond_to?(:to_time)
-      to_time = to_time.to_time if !to_time.is_a?(Time) && to_time.respond_to?(:to_time)
+      from_time = coerce_to_time(from_time)
+      to_time = coerce_to_time(to_time)
 
       DOTIW::TimeHash.new(nil, from_time, to_time, options).to_hash
     end
@@ -73,12 +73,28 @@ module DOTIW
       if value.is_a?(Numeric)
         Time.at(value)
       elsif value.respond_to?(:to_time)
-        value.to_time
+        coerce_to_time(value)
       else
         raise ArgumentError, "#{value.inspect} can't be converted to a Time value"
       end
     end
 
+    # An ActiveSupport::TimeWithZone already carries its zone explicitly and
+    # supports every operation TimeHash needs (arithmetic, #advance, calendar
+    # accessors, #utc_offset), so there's no reason to convert it to a plain
+    # Time first. Doing so is actively harmful: on Rails < 8.0 (before
+    # to_time_preserves_timezone defaulted to :zone), TimeWithZone#to_time
+    # discards the real zone and returns a Time in the process's local zone
+    # instead, which loses the information TimeHash's same_clock? needs to
+    # correctly fold a historical UTC offset change into the distance
+    # (#153/#162/#165) on Rails < 8.0 (#170) - the loss isn't inherent to
+    # older Rails, it's an unforced conversion we don't need to make.
+    def coerce_to_time(value)
+      return value if value.is_a?(Time) || value.respond_to?(:time_zone)
+
+      value.to_time
+    end
+
     def options_with_scope(options)
       if options.key?(:compact)
         options.merge(scope: DOTIW::DEFAULT_I18N_SCOPE_COMPACT)
@@ -102,9 +118,23 @@ module DOTIW
       options[:except] = Array.wrap(options[:except]).map!(&:to_sym) if options[:except]
       options[:only] = Array.wrap(options[:only]).map!(&:to_sym) if options[:only]
 
-      DOTIW::TimeHash::TIME_FRACTIONS.each do |fraction|
-        if options[:except]&.include?(fraction) || (options[:only] && !options[:only].include?(fraction))
-          discarded_hash[fraction] = hash.delete fraction
+      if options[:except] || options[:only]
+        # Fold excluded fractions into the next smaller fraction instead of discarding their
+        # duration outright, e.g. weeks excluded via only: [:years, :months, :days] are converted
+        # to days and added to the days count, rather than losing those weeks entirely. Larger
+        # fractions are processed first so that a run of consecutive excluded fractions cascades
+        # down to the largest fraction that's still included (or is dropped if none remain).
+        DOTIW::TimeHash::TIME_FRACTIONS.reverse_each do |fraction|
+          next unless hash.key?(fraction)
+          next unless options[:except]&.include?(fraction) || (options[:only] && !options[:only].include?(fraction))
+
+          value = hash.delete(fraction)
+          discarded_hash[fraction] = value
+
+          next_fraction = _next_smaller_fraction(fraction)
+          next unless next_fraction
+
+          hash[next_fraction] = hash.fetch(next_fraction, 0) + (value * ROLLUP_THRESHOLDS[next_fraction])
         end
       end
 
@@ -117,12 +147,13 @@ module DOTIW
         fractions &= options[:only] if options[:only]
         fractions -= options[:except] if options[:except]
 
-        I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-          # e.g. try to format 'less than 1 days', fallback to '0 days'
-          return locale.translate :less_than_x,
-                                  distance: locale.translate(fractions.first, count: 1),
-                                  default: locale.translate(fractions.first, count: 0)
-        end
+        locale = options[:locale]
+        # e.g. try to format 'less than 1 days', fallback to '0 days'
+        return I18n.translate :less_than_x,
+                              locale: locale,
+                              scope: i18n_scope,
+                              distance: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 1),
+                              default: I18n.translate(fractions.first, locale: locale, scope: i18n_scope, count: 0)
       end
 
       options.delete(:except)
@@ -137,10 +168,8 @@ module DOTIW
         _maybe_round! hash, discarded_hash, highest_measures[:remainder]
       end
 
-      phrases = []
-      I18n.with_options locale: options[:locale], scope: i18n_scope do |locale|
-        phrases = hash.map { |key, value| locale.t(key, count: value) }
-      end
+      locale = options[:locale]
+      phrases = hash.map { |key, value| I18n.translate(key, locale: locale, scope: i18n_scope, count: value) }
 
       options[:words_connector] ||= I18n.translate :"#{i18n_scope}.words_connector",
                                                    default: :'support.array.words_connector',
@@ -152,7 +181,7 @@ module DOTIW
                                                        default: :'support.array.last_word_connector',
                                                        locale: options[:locale]
 
-      phrases.to_sentence(options.except(:accumulate_on, :compact))
+      phrases.to_sentence(options.except(:accumulate_on, :max_unit, :compact))
     end
 
     def _compute_highest_measures!(options)
@@ -192,6 +221,13 @@ module DOTIW
       end
     end
 
+    def _next_smaller_fraction(fraction)
+      index = DOTIW::TimeHash::TIME_FRACTIONS.index(fraction)
+      return nil if index.nil? || index.zero?
+
+      DOTIW::TimeHash::TIME_FRACTIONS[index - 1]
+    end
+
     def _rollup!(hash, smallest_measure_index)
       DOTIW::TimeHash::TIME_FRACTIONS[smallest_measure_index..-1].each_with_index do |fraction, index|
         if hash.fetch(fraction, 0) >= ROLLUP_THRESHOLDS[fraction]