amounts 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c850c2cdba4add1e09b4d6b5bfe0d1d45ffd9002924a24f5ad59e63a9f4ca513
-  data.tar.gz: bd146211750f51dc54e3967a3f2937eea48334cc88f1c0480b48f199c038e7fa
+  metadata.gz: 494f30811e40cd1e304c944fe6033f33d1c64f2a6e962e3636e2d43eb702db4d
+  data.tar.gz: 1b1f175209a0b3adb1cb48ad0c8429dcb5f3e0f0fe2558ee0cbbd8616b3a4714
 SHA512:
-  metadata.gz: ff1b3637f8a8df2b98a8c64975f1f0eef01f876bf8239b36a097624a3cc7218477da32d7dc95d26d22f11a83068dabf2306195480efc1d9f65007e01e3308ef1
-  data.tar.gz: 947b9a81380612ca2b0f4ccd234936fca76f479bed1be42096a45715a1cd59fb80ead76089b4cb0c8120f8bf1d8fbe3b26c88c9a9860c39265d0f2bcbc1719da
+  metadata.gz: c70c23049b1f4932b122628c71a8fa66d079e387f8a2b9f6ff967dc3cbfb2921628eb7b633afaf54bd9f47a785f90b9f2ccc78e50d46a129d8b418c5cd3aacf7
+  data.tar.gz: 700869d84355a4bcc8bd126fe93ea05c9e9574dad67d88124f091b28161eef45056c10e4507fbc62467868a9515822b0522b1c0074437e6fba9ee838573f6ee9

data/.rubocop.yml

@@ -1,3 +1,9 @@
+require:
+  - ./rubocop/cop/amounts/one_assertion_per_test
+  - ./rubocop/cop/amounts/one_test_class_per_file
+  - ./rubocop/cop/amounts/mirrored_test_path
+  - ./rubocop/cop/amounts/concern_naming
+
 AllCops:
   NewCops: enable
   SuggestExtensions: false
@@ -87,3 +93,34 @@ Gemspec/DevelopmentDependencies:
 
 Gemspec/RequireMFA:
   Enabled: false
+
+# Project cops (rubocop/cop/amounts/). See .claude/rules/tests.md.
+Amounts/OneAssertionPerTest:
+  Enabled: true
+  Include:
+    - "test/**/*_test.rb"
+    - "spec/**/*_spec.rb"
+
+Amounts/OneTestClassPerFile:
+  Enabled: true
+  Include:
+    - "test/**/*_test.rb"
+    - "spec/**/*_spec.rb"
+
+Amounts/MirroredTestPath:
+  Enabled: true
+  Include:
+    - "test/**/*_test.rb"
+    - "spec/**/*_spec.rb"
+  # These directories don't mirror lib/ (see .claude/rules/tests.md).
+  Exclude:
+    - "test/support/**/*"
+    - "test/dummy/**/*"
+    - "test/integration/**/*"
+    - "spec/support/**/*"
+
+# See .claude/rules/concerns.md.
+Amounts/ConcernNaming:
+  Enabled: true
+  Include:
+    - "lib/amount/concerns/**/*.rb"

data/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## 0.1.0 - 2026-11-02
+
+### Added
+
+- Compact notation for large numbers: `ui(compact: true)` renders `50M TOKENS`
+  or `$1.5M`. It keeps 3 significant digits (`compact: { precision: 2 }` to
+  change it), rounds in `direction:` (so `1_999_999` floors to `1.99M`), trims
+  trailing zeros and moves up a scale when rounding reaches it. Numbers below
+  one thousand are formatted as usual. Scale words run from `K`/`M`/`B`/`T`
+  through `Qa`/`Qi`/`Sx`/`Sp`/`Oc`/`No` to `Dc` (decillion, 10^33), joined
+  as `"%n%u"`; when localizing they come from
+  `number.human.decimal_units.units` (pluralized with the compacted number)
+  joined by `number.human.decimal_units.format` (default `"%n %u"`), falling
+  back to the short form for a missing word. Works with `unit:` (the scaled
+  number is compacted), labels and templates (which wrap the compacted
+  number; plural labels agree with the full value) and `decorated: false`.
+  Output without `compact:` is unchanged.
+- `Amount.parse_ui(input, symbol, locale: nil)` parses what a person types in a
+  locale's number format: `parse_ui("1.500,50", :USD, locale: :de)` and
+  `parse_ui("1,500.50", :USD, locale: :en)` both give `USD|1500.50`. The
+  effective locale is `locale:`, then `I18n.locale` when `Amount.localize` is
+  true, else plain parsing (`.` decimal, no delimiters). Accepts surrounding
+  whitespace (including NBSP), a leading `-` or `+`, delimiters in correct
+  groups of three, and the type's label or display symbol at either end in any
+  plural form (`"$1,500.50"`, `"1.500,50 €"`). Raises `InvalidInput` for more
+  decimals than the type has (never rounds), misplaced delimiters, a repeated
+  separator, another type's label, or empty input. Returns the type's
+  registered class; an unregistered symbol raises as `Amount.new` does.
+  `Amount.parse` and the constructors are unchanged. Wiring it into the
+  ActiveRecord type is not part of this change.
+- Templates for where the number and unit go. `register` takes
+  `display_format:` and display unit specs take `format:`, where `%n` is the
+  formatted number (sign included) and `%u` the label: `"%u%n"`,
+  `"%n\u00A0%u"`. Templates are used exactly as given, so non-breaking spaces
+  survive. When localizing, `amounts.formats.<symbol downcased>` and
+  `amounts.display_unit_formats.<symbol downcased>.<unit>` override them; a
+  locale template without `%n` is ignored. `display_position` stays as
+  shorthand for `"%u%n"` / `"%n %u"`, so existing output is unchanged.
+  Passing both `display_format:` and `display_position:` raises
+  `ArgumentError`; a display unit with both `:format` and `:position` raises
+  `InvalidDisplayUnit`. `Registry::Entry#display_format` always holds the
+  type's template, and `#display_position` is `nil` for a type registered
+  with `display_format:`.
+- `Amount#display_format(unit: nil, locale: nil)` returns the template `ui`
+  uses for the type or a display unit, with the same locale precedence.
+  Template behavior lives in the new `Amount::Formattable` concern, included
+  in `Amount`.
+- `Registry::Entry#display_unit(unit)` returns a display unit's spec, raising
+  `InvalidDisplayUnit` for an unknown unit.
+- Plural unit labels. `display_symbol:` (and a display unit's `symbol:`) accept
+  a hash such as `{ one: "search", other: "searches" }`, giving `1 search` /
+  `2 searches`. `register` raises (`Registry::InvalidDisplaySymbol`, or
+  `InvalidDisplayUnit` for a unit) unless the hash has `:other` and maps
+  Symbols to Strings. The count is the displayed number (after scaling and
+  rounding). Without localizing, `:one` is used when it equals 1, else
+  `:other`; when localizing, I18n translations and hashes are pluralized with
+  `count:` through the locale's rules (`few`, `many`, ...). A missing form falls
+  back to `:other`. `unit_label` takes `count:`; without it the `:other` form is
+  used. String labels are unchanged.
+- Unit labels can come from I18n. `register` takes `label_key:` (String or
+  Symbol); without it the key is `amounts.units.<symbol downcased>`. Display
+  units take `label_key:` in their spec, defaulting to
+  `amounts.display_units.<symbol downcased>.<unit>`. Lookups only happen when
+  localizing (`locale:` or `Amount.localize = true`). Fallbacks: a type falls
+  back to `display_symbol`; a display unit to its `:symbol`, then the type's
+  label. A missing key never renders "translation missing". Output is
+  unchanged when not localizing.
+- `Amount#unit_label(unit: nil, locale: nil)` returns the label alone, with
+  the same rules as `ui`, for column headers and chips.
+- `ui` can format numbers for a locale: `ui(locale: :de)` uses the locale's
+  `number.format` delimiter and separator (`"$122.500,00"`), falling back to
+  `,` and `.` for missing keys. Works with `unit:`, `decorated: false`,
+  `trim_zeros` and `direction`.
+- `Amount.localize = true` makes `ui` use `I18n.locale` when no `locale:` is
+  given. It defaults to `false`, so output is unchanged unless you opt in.
+  Passing `locale:` or setting `Amount.localize = true` without the `i18n` gem
+  loaded raises `ArgumentError`. `to_s`, `formatted`, `as_json`, serialization
+  and `Amount.parse` never change with the locale.
+
+### Changed
+
+- `Amount`'s internal concern modules are renamed as -able adjectives and live
+  in `lib/amount/concerns/`: `Arithmetic` → `Calculable`, `Allocation` →
+  `Allocatable`, `Comparison` → `Orderable`, `Conversion` → `Convertible`,
+  `Serialization` → `Serializable` (`Formattable` is unchanged). Five new
+  concerns hold logic that used to sit in `Amount` itself: `Registrable`,
+  `Localizable`, `Parsable`, `Constructible` and `Coercible`. None of these
+  modules are documented API, and every `Amount` method is unchanged. Code
+  that referenced a module by name, or required a file under `amount/`
+  other than the documented entry points, should `require "amount"` and call
+  `Amount`'s methods.
+- `AmountValidator` now adds errors by I18n key instead of hard-coded English
+  strings, so apps can translate or reword them: `:amount_type`,
+  `:amount_symbol`, `:amount_invalid_constraint`, `:amount_incomparable`, plus
+  Rails' own `:greater_than`, `:greater_than_or_equal_to`, `:less_than`,
+  `:less_than_or_equal_to` and `:invalid`. English defaults ship in
+  `lib/amount/active_record/locale/en.yml`, loaded into `I18n.load_path` when
+  `amount/active_record` is required (once, with or without Rails). With no app
+  translations, message text is unchanged. `errors.details` now reports the
+  keys and interpolation values.
+
+### Fixed
+
+- Anonymous ActiveRecord classes using `has_amount` get a fallback
+  `model_name`, so validation messages can be generated for them.
+- On Rails 8.1, assigning an amount whose atomic value has more than 16 digits
+  (`Amount.new(10**30, :SOL, from: :atomic)`) silently truncated it before
+  saving (to `10**15`). Rails 8.1 cuts a string cast to an integer column to
+  16 bytes, and `has_amount` wrote the atomic value as a string. It now writes
+  the Integer, which every Rails version stores exactly. Reads were never
+  affected; rows already written under Rails 8.1 with more than 16 digits
+  hold the truncated value.
+
 ## 0.0.8 - 2026-05-05
 
 ### Changed

data/Gemfile

@@ -12,6 +12,10 @@ group :development do
   gem "irb", ">= 1.13"
 end
 
+group :test do
+  gem "i18n", ">= 1.14"
+end
+
 group :quality do
   gem "rubocop", "~> 1.63.0"
 end

data/README.md

@@ -215,8 +215,193 @@ amount.ui
 amount.ui(direction: :ceil)
 amount.ui(unit: :gram)
 amount.in_unit(:gram)
+amount.ui(locale: :de)   # => "$122.500,00" (needs the i18n gem)
+amount.ui(compact: true) # => "$1.5M" for 1,500,000
+
+Amount.localize = true   # ui follows I18n.locale
+```
+
+`ui` formats numbers for a locale (thousands delimiter and decimal separator
+from `number.format`) only when you pass `locale:` or set `Amount.localize = true`.
+Both require I18n to be loaded and raise `ArgumentError` otherwise. `to_s`,
+`formatted`, serialization and `Amount.parse` never depend on the locale.
+
+Unit labels can be translated too. When localizing, the label comes from the
+type's `label_key:` (default `amounts.units.<symbol downcased>`), then falls back
+to `display_symbol`. Display units use their spec's `label_key:` (default
+`amounts.display_units.<symbol downcased>.<unit>`), then the unit's `:symbol`,
+then the type's label. Missing keys never yield "translation missing".
+
+```yaml
+en:
+  amounts:
+    display_units:
+      gold: { oz_t: "oz t", gram: "g", kg: "kg" }
+de:
+  amounts:
+    display_units:
+      gold: { oz_t: "Feinunze", gram: "Gramm", kg: "Kilogramm" }
+```
+
+```ruby
+gold = Amount.of_gold("12.5")   # :GOLD with oz_t / gram / kg display units
+
+gold.ui(unit: :gram, locale: :en)          # => "388.79 g"
+gold.ui(unit: :gram, locale: :de)          # => "388,79 Gramm"
+gold.ui(unit: :kg,   locale: :de)          # => "0,38879 Kilogramm"
+gold.unit_label(unit: :kg, locale: :de)    # => "Kilogramm"
+gold.unit_label(unit: :gram)               # => "g" (not localizing)
+
+Amount.register :SEARCHES, decimals: 0, label_key: "amounts.units.searches"
+Amount.of_searches(3).unit_label(locale: :de)  # => "Suchen" (with that key in de)
+```
+
+`unit_label(unit: nil, locale: nil, count: nil)` returns the label alone, following
+the same rules as `ui`.
+
+### Parsing typed input
+
+`Amount.parse_ui` reads what a person types, in a locale's number format. The
+locale is `locale:`, then `I18n.locale` when `Amount.localize` is true, else
+plain parsing (`.` decimal, no delimiters). `Amount.parse` stays the compact
+wire format.
+
+```ruby
+Amount.parse_ui("1.500,50", :USD, locale: :de)   # => USD|1500.50
+Amount.parse_ui("1,500.50", :USD, locale: :en)   # => USD|1500.50
+Amount.parse_ui("1500.50", :USD)                 # => USD|1500.50
+Amount.parse_ui("1.500,50 €", :EUR, locale: :de) # label at either end, any plural form
 ```
 
+It accepts surrounding whitespace (including NBSP), a leading `-` or `+`, and
+delimiters in groups of three. It raises `Amount::InvalidInput` for more
+decimal places than the type has (it never rounds), misplaced delimiters
+(`"1,50,0"`), a repeated separator, another type's label, or empty input.
+`ui(locale:)` output round-trips through `parse_ui(..., locale:)`.
+
+### Plural labels
+
+Labels can agree with the number: `1 search`, `2 searches`. `count` is the
+number as displayed, after unit scaling and rounding (`direction:`) and before
+formatting, so `1.00` is one and `1.50` is other.
+
+In code, without I18n, give `display_symbol:` (or a display unit's `symbol:`) a
+hash. It must have `:other`; `register` raises otherwise.
+
+```ruby
+Amount.register :SEARCHES, decimals: 0, display_symbol: { one: "search", other: "searches" }
+
+Amount.of_searches(1).ui   # => "1 search"
+Amount.of_searches(0).ui   # => "0 searches"
+Amount.of_searches(2).ui   # => "2 searches"
+```
+
+The hash uses `:one` when the displayed number equals 1, else `:other`. When
+localizing with I18n loaded, the locale's pluralization rules decide instead,
+so a hash can carry `few`, `many`, ... too. I18n translations can be plural
+hashes as well:
+
+```yaml
+en:
+  amounts:
+    units:
+      searches:
+        one: "search"
+        other: "searches"
+```
+
+`unit_label(count: nil)` takes the same behavior; without a number it uses
+`:other`: `Amount.of_searches(1).unit_label(count: 1) # => "search"`.
+String labels behave exactly as before.
+
+Where the number and label go is a template, like Rails'
+`number.currency.format.format`: `%n` is the formatted number (sign included)
+and `%u` the label. Set it with `display_format:` on `register` or `format:` on
+a display unit. `display_position` is shorthand for one: `:prefix` is `"%u%n"`
+and `:suffix` (the default) is `"%n %u"`. A type takes one or the other;
+passing both raises `ArgumentError`.
+
+```ruby
+Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u%n"
+```
+
+When localizing, `amounts.formats.<symbol downcased>` (and
+`amounts.display_unit_formats.<symbol downcased>.<unit>` for display units)
+overrides the configured template:
+
+```yaml
+de:
+  amounts:
+    formats:
+      eur: "%n\u00A0%u"   # non-breaking space: "12,50 €" never wraps apart
+```
+
+```ruby
+Amount.of_eur("12.5").ui(locale: :en)                    # => "€12.50"
+Amount.of_eur("12.5").ui(locale: :de)                    # => "12,50\u00A0€"
+Amount.of_eur("12.5").ui(locale: :de, decorated: false)  # => "12,50"
+```
+
+Templates are used exactly as given; nothing inserts non-breaking spaces for
+you, so put them in your locale files. Negative numbers keep their sign inside
+`%n` (`"$-5.00"`).
+
+`display_format(unit: nil, locale: nil)` returns the template `ui` would use,
+for rendering the number and label yourself:
+
+```ruby
+Amount.of_eur("12.5").display_format(locale: :de)  # => "%n\u00A0%u"
+```
+
+### Compact notation
+
+`ui(compact: true)` shortens numbers of one thousand or more: `50M`, `$1.5M`.
+It keeps 3 significant digits (`compact: { precision: 2 }` changes that),
+rounds in `direction:` (floor by default, so `1_999_999` is `1.99M`, never
+`2M`) and trims trailing zeros. Below one thousand the number is formatted as
+usual. Not using `compact:` leaves output unchanged.
+
+```ruby
+Amount.register :TOKENS, decimals: 0
+
+Amount.of_tokens(50_000_000).ui(compact: true)                    # => "50M TOKENS"
+Amount.of_tokens(1_999_999).ui(compact: true)                     # => "1.99M TOKENS"
+Amount.of_tokens(1_999_999).ui(compact: true, direction: :ceil)   # => "2M TOKENS"
+Amount.of_tokens(1_299_999).ui(compact: { precision: 2 })         # => "1.2M TOKENS"
+Amount.of_tokens(50_000_000).ui(compact: true, decorated: false)  # => "50M"
+Amount.of_usd("1500000").ui(compact: true)                        # => "$1.5M"
+Amount.of_gold("1000").ui(unit: :gram, compact: true)             # => "31.1K g"
+```
+
+Not localizing, the scale words are `K`, `M`, `B`, `T`, `Qa` (quadrillion),
+`Qi` (quintillion), `Sx`, `Sp`, `Oc`, `No` and `Dc` (decillion, 10^33), joined
+as `"%n%u"`. When localizing, they come from `number.human.decimal_units.units`
+(`thousand`, `million`, `billion`, `trillion`, `quadrillion`, `quintillion`,
+`sextillion`, `septillion`, `octillion`, `nonillion`, `decillion`, optionally
+plural hashes counted with the compacted number), joined by
+`number.human.decimal_units.format` (default `"%n %u"`), the same keys Rails'
+`number_to_human` reads (Rails itself stops at `quadrillion`). A scale with no
+translation falls back to its short form. Numbers past decillions stay in
+decillions (`1500Dc`).
+
+```yaml
+de:
+  number:
+    human:
+      decimal_units:
+        format: "%n %u"
+        units: { thousand: "Tsd.", million: "Mio.", billion: "Mrd." }
+  amounts:
+    units: { tokens: "Token" }
+```
+
+```ruby
+Amount.of_tokens(1_500_000).ui(compact: true, locale: :de)  # => "1,5 Mio. Token"
+```
+
+The type's label and template wrap the compacted number, and a plural label
+agrees with the full value (`1K searches`), not the compacted digits.
+
 ### Serialization
 
 ```ruby
@@ -316,6 +501,35 @@ ALTER TABLE holdings ADD CONSTRAINT amount_both_or_neither
   CHECK ((amount_atomic IS NULL) = (amount_symbol IS NULL));
 ```
 
+### Validation messages
+
+`validates :amount, amount: { symbol: :USDC, greater_than: 0 }` adds errors by
+I18n key, so apps can translate or reword them. The English defaults ship in
+`lib/amount/active_record/locale/en.yml`, which the gem adds to `I18n.load_path`
+when `amount/active_record` loads (Rails or plain ActiveRecord).
+
+| Case | Key | Interpolations | English default |
+|---|---|---|---|
+| Not an Amount | `:amount_type` | | `must be an Amount` |
+| Wrong symbol | `:amount_symbol` | `expected` | `must have symbol %{expected}` |
+| Invalid constraint | `:amount_invalid_constraint` | `option`, `message` | `has invalid %{option} constraint: %{message}` |
+| Incomparable | `:amount_incomparable` | `symbol`, `other_symbol`, `option` | `cannot compare %{symbol} to %{other_symbol} for %{option}` |
+| Comparisons | Rails' `:greater_than`, `:greater_than_or_equal_to`, `:less_than`, `:less_than_or_equal_to` | `count` (the other amount's `to_s`) | Rails' own, e.g. `must be greater than %{count}` |
+| Fallback | Rails' `:invalid` | | `is invalid` |
+
+Override any of them in your own locale files:
+
+```yaml
+de:
+  errors:
+    messages:
+      amount_symbol: "muss das Symbol %{expected} haben"
+```
+
+`record.errors.details` reports the keys and interpolation values.
+Apps that already translate Rails' `greater_than` etc. get those translations
+for free.
+
 ### SQLite Note
 
 The adapter supports SQLite for general integration tests and development, but SQLite does not preserve `DECIMAL(78,0)` values above 64-bit range exactly under ActiveRecord's default numeric handling. For exact wei-scale persistence, use PostgreSQL or another database with true arbitrary-precision numeric behavior.
@@ -334,7 +548,7 @@ Run the PostgreSQL integration test explicitly:
 
 ```bash
 AMOUNTS_POSTGRES_URL=postgresql://localhost/amounts_test \
-  bundle exec ruby -Ilib:test test/postgresql_integration_test.rb
+  bundle exec rake test:integration
 ```
 
 If `AMOUNTS_POSTGRES_URL` is not set, the PostgreSQL test file skips cleanly.

data/Rakefile

@@ -2,17 +2,54 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
-Rake::TestTask.new(:test) do |task|
-  task.libs << "lib"
-  task.libs << "test"
-  task.pattern = "test/**/*_test.rb"
+
+# Each group runs in its own process: ActiveSupport patches core classes, and
+# test/dummy (integration) defines models that collide with the SQLite ones.
+TEST_GROUPS = {
+  core: FileList["test/amount_test.rb", "test/amount/**/*_test.rb"].exclude(
+    "test/amount/active_record_test.rb", "test/amount/active_record/**/*"
+  ),
+  active_record: FileList[
+    "test/amount/active_record_test.rb", "test/amount/active_record/**/*_test.rb", "test/generators/**/*_test.rb"
+  ],
+  integration: FileList["test/integration/**/*_test.rb"]
+}.freeze
+
+namespace :test do
+  TEST_GROUPS.each do |group, files|
+    Rake::TestTask.new(group) do |task|
+      task.libs << "lib" << "test"
+      task.test_files = files
+    end
+  end
+end
+
+desc "Run every Minitest group"
+task test: TEST_GROUPS.keys.map { |group| "test:#{group}" }
+
+# RuboCop and RSpec are optional bundle groups in CI; define their tasks only
+# when installed.
+begin
+  require "rspec/core/rake_task"
+
+  namespace :spec do
+    RSpec::Core::RakeTask.new(:core) { |task| task.pattern = "spec/amount/rspec/**/*_spec.rb" }
+    RSpec::Core::RakeTask.new(:active_record) { |task| task.pattern = "spec/amount/active_record/**/*_spec.rb" }
+  end
+
+  desc "Run every RSpec group"
+  task spec: %w[spec:core spec:active_record]
+rescue LoadError
+  nil
 end
 
-RuboCop::RakeTask.new(:rubocop)
-RSpec::Core::RakeTask.new(:spec)
+begin
+  require "rubocop/rake_task"
 
-task lint: %i[rubocop]
+  RuboCop::RakeTask.new(:rubocop)
+  task lint: %i[rubocop]
+rescue LoadError
+  nil
+end
 
-task default: %i[test spec rubocop]
+task default: %i[test spec lint]

data/lib/amount/active_record/amount_validator.rb

@@ -41,7 +41,7 @@ class Amount
       def validate_amount_instance(record, attribute, value)
         return if value.is_a?(::Amount)
 
-        record.errors.add(attribute, "must be an Amount")
+        record.errors.add(attribute, :amount_type)
       end
 
       def validate_symbol(record, attribute, value)
@@ -49,7 +49,7 @@ class Amount
         return unless expected_symbol
         return if value.symbol == expected_symbol
 
-        record.errors.add(attribute, "must have symbol #{expected_symbol}")
+        record.errors.add(attribute, :amount_symbol, expected: expected_symbol)
       end
 
       def validate_comparators(record, attribute, value)
@@ -61,7 +61,7 @@ class Amount
 
           compare_amounts(record, attribute, value, operator, other, option_name)
         rescue ::Amount::Error, ArgumentError => error
-          record.errors.add(attribute, "has invalid #{option_name} constraint: #{error.message}")
+          record.errors.add(attribute, :amount_invalid_constraint, option: option_name, message: error.message)
         end
       end
 
@@ -78,28 +78,19 @@ class Amount
       def compare_amounts(record, attribute, value, operator, other, option_name)
         comparison = value <=> other
         if comparison.nil?
-          record.errors.add(attribute, "cannot compare #{value.symbol} to #{other.symbol} for #{option_name}")
+          record.errors.add(attribute, :amount_incomparable,
+                            symbol: value.symbol, other_symbol: other.symbol, option: option_name)
           return
         end
 
         return if comparison.public_send(operator, 0)
 
-        record.errors.add(attribute, failure_message(option_name, other))
+        record.errors.add(attribute, failure_key(option_name), count: other.to_s)
       end
 
-      def failure_message(option_name, other)
-        case option_name
-        when :greater_than
-          "must be greater than #{other}"
-        when :greater_than_or_equal_to
-          "must be greater than or equal to #{other}"
-        when :less_than
-          "must be less than #{other}"
-        when :less_than_or_equal_to
-          "must be less than or equal to #{other}"
-        else
-          "is invalid"
-        end
+      # Rails' own keys, so apps that translate them get these for free.
+      def failure_key(option_name)
+        COMPARATORS.key?(option_name) ? option_name : :invalid
       end
 
       def fetch_definition(record, attribute)

data/lib/amount/active_record/attribute_definition.rb

@@ -41,7 +41,9 @@ class Amount
           return nil
         end
 
-        record.write_attribute(atomic_column, value.atomic.to_s)
+        # The Integer itself, not its string: Rails 8.1 cuts a String cast to an
+        # integer column to 16 bytes, which silently truncates large values.
+        record.write_attribute(atomic_column, value.atomic)
         record.write_attribute(symbol_column, value.symbol.to_s) unless fixed_symbol?
         value
       end

data/lib/amount/active_record/locale/en.yml

@@ -0,0 +1,7 @@
+en:
+  errors:
+    messages:
+      amount_type: "must be an Amount"
+      amount_symbol: "must have symbol %{expected}"
+      amount_invalid_constraint: "has invalid %{option} constraint: %{message}"
+      amount_incomparable: "cannot compare %{symbol} to %{other_symbol} for %{option}"

data/lib/amount/active_record/model.rb

@@ -15,6 +15,15 @@ class Amount
         define_amount_validation(definition)
       end
 
+      # Anonymous classes have no `model_name`, which Rails needs to build
+      # messages from error keys. Fall back to a stable placeholder so
+      # validations on `Class.new(ApplicationRecord)` models still report.
+      def model_name
+        return super if name
+
+        @model_name ||= ::ActiveModel::Name.new(self, nil, "AnonymousModel")
+      end
+
       def amount_attribute_definitions
         @amount_attribute_definitions ||= {}
       end

data/lib/amount/active_record.rb

@@ -24,6 +24,17 @@ class Amount
   #     has_amount :fee, symbol: :SOL
   #   end
   module ActiveRecord
+    # English defaults for the validator's error keys. Apps override them in
+    # their own locale files.
+    LOCALE_PATH = File.expand_path("active_record/locale/en.yml", __dir__).freeze
+
+    # Registers the gem's locale file with I18n, once.
+    #
+    # @return [void]
+    def self.install_locale!
+      ::I18n.load_path << LOCALE_PATH unless ::I18n.load_path.include?(LOCALE_PATH)
+    end
+
     # Installs the migration DSL and model macros into ActiveRecord.
     #
     # This is called automatically when the file is required.
@@ -41,4 +52,5 @@ class Amount
   end
 end
 
+Amount::ActiveRecord.install_locale!
 Amount::ActiveRecord.install!