Merge pull request #45470 from AlexB52/doc-full-message-format

Add Formatting Full Messages with I18n section in ActiveRecordValidations guides [ci-skip]

(cherry picked from commit e722b74)

guides/source/active_record_validations.md

@@ -1275,7 +1275,7 @@ irb> error.full_message
 => "Name is too short (minimum is 3 characters)"
 ```
 
-The [`full_message`][] method generates a more user-friendly message, with the capitalized attribute name prepended.
+The [`full_message`][] method generates a more user-friendly message, with the capitalized attribute name prepended. (To customize the format that `full_message` uses, see the [I18n guide](i18n.html#active-model-methods).)
 
 [`full_message`]: https://api.rubyonrails.org/classes/ActiveModel/Errors.html#method-i-full_message
 [`where`]: https://api.rubyonrails.org/classes/ActiveModel/Errors.html#method-i-where

guides/source/configuring.md

@@ -685,7 +685,52 @@ Sets fallback behavior for missing translations. Here are 3 usage examples for t
 
 #### `config.active_model.i18n_customize_full_message`
 
-Is a boolean value which controls whether the `full_message` error format can be overridden at the attribute or model level in the locale files. This is `false` by default.
+Controls whether the [`Error#full_message`][ActiveModel::Error#full_message] format can be overridden in an i18n locale file. Defaults to `false`.
+
+When set to `true`, `full_message` will look for a format at the attribute and model level of the locale files. The default format is `"%{attribute} %{message}"`, where `attribute` is the name of the attribute, and `message` is the validation-specific message. The following example overrides the format for all `Person` attributes, as well as the format for a specific `Person` attribute (`age`).
+
+```ruby
+class Person
+  include ActiveModel::Validations
+
+  attr_accessor :name, :age
+
+  validates :name, :age, presence: true
+end
+```
+
+```yml
+en:
+  activemodel: # or activerecord:
+    errors:
+      models:
+        person:
+          # Override the format for all Person attributes:
+          format: "Invalid %{attribute} (%{message})"
+          attributes:
+            age:
+              # Override the format for the age attribute:
+              format: "%{message}"
+              blank: "Please fill in your %{attribute}"
+```
+
+```irb
+irb> person = Person.new.tap(&:valid?)
+
+irb> person.errors.full_messages
+=> [
+  "Invalid Name (can't be blank)",
+  "Please fill in your Age"
+]
+
+irb> person.errors.messages
+=> {
+  :name => ["can't be blank"],
+  :age  => ["Please fill in your Age"]
+}
+```
+
+[ActiveModel::Error#full_message]: https://api.rubyonrails.org/classes/ActiveModel/Error.html#method-i-full_message
 
 ### Configuring Active Record
 

guides/source/i18n.md

@@ -1055,7 +1055,9 @@ Rails uses fixed strings and other localizations, such as format strings and oth
 
 * `ActiveModel::Errors#generate_message` (which is used by Active Model validations but may also be used manually) uses `model_name.human` and `human_attribute_name` (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes".
 
-* `ActiveModel::Errors#full_messages` prepends the attribute name to the error message using a separator that will be looked up from [errors.format](https://github.com/rails/rails/blob/main/activemodel/lib/active_model/locale/en.yml#L4) (and which defaults to `"%{attribute} %{message}"`).
+* `ActiveModel::Error#full_message` and `ActiveModel::Errors#full_messages` prepend the attribute name to the error message using a format looked up from `errors.format` (default: [`"%{attribute} %{message}"`](https://github.com/rails/rails/blob/main/activemodel/lib/active_model/locale/en.yml#L4)). To customize the default format, override it in the app's locale files. To customize the format per model or per attribute, see [`config.active_model.i18n_customize_full_message`][].
+
+[`config.active_model.i18n_customize_full_message`]: configuring.html#config-active-model-i18n-customize-full-message
 
 #### Active Support Methods