How to Customize Ransack i18n Translation Files: A Complete Guide

You can customize Ransack's i18n translation files by adding YAML files to your Rails application's config/locales directory, which will override the default translations shipped in lib/ransack/locale/*.yml according to standard Rails I18n precedence rules.

Ransack, the popular search library for Ruby on Rails maintained by activerecord-hackery/ransack, provides extensive internationalization support out of the box. When you need to customize the default text for search predicates, model names, or UI elements, understanding how Ransack loads and prioritizes translation files is essential.

Understanding Ransack's Default i18n Structure

Ransack automatically injects its locale files into the Rails I18n load path when the library initializes. In lib/ransack/translate.rb, lines 3-5, the library appends its locale directory to I18n.load_path:

# lib/ransack/translate.rb – lines 3-5

I18n.load_path += Dir[
  File.join(File.dirname(__FILE__), 'locale'.freeze, '*.yml'.freeze)
]

The default translation files are located in lib/ransack/locale/ and include en.yml for English translations. These files contain keys for predicates (like eq, lt, cont), logical operators (and, or), and search-related terminology.

Overriding Translations in Your Rails Application

Because Ransack uses standard Rails I18n, you can override any translation key by creating YAML files in your application's config/locales directory. Rails merges all files on the load path, with later entries taking precedence over earlier ones.

Core Words and Predicates

To customize basic search terminology and predicate labels, override the ransack namespace keys:

# config/locales/ransack_custom.yml

en:
  ransack:
    and: "and also"
    or: "or alternatively"
    search: "Find records"
    predicates:
      eq: "equals exactly"
      lt: "less than"
      cont: "contains"

Model and Attribute Names

Ransack looks for model names under ransack.models and attributes under ransack.attributes:

# config/locales/ransack_models.yml

es:
  ransack:
    models:
      user: "Usuario"
      post: "Publicación"
    attributes:
      user:
        name: "Nombre completo"
        email: "Correo electrónico"
      post:
        title: "Título del artículo"

Associations

For search forms that traverse associations, customize the association labels:

# config/locales/ransack_associations.yml

es:
  ransack:
    associations:
      user:
        posts: "Entradas publicadas"
        comments: "Comentarios realizados"

Controlling i18n Load Order

If you need your translations to be evaluated before Ransack's defaults—ensuring that missing keys don't fall back to the library's built-in values—you can manually prepend your locale file to the load path in an initializer:

# config/initializers/ransack_i18n.rb

I18n.load_path.unshift(
  Rails.root.join('config', 'locales', 'ransack_custom.yml').to_s
)

However, for most customization scenarios, simply placing files in config/locales is sufficient. The standard Rails initialization process loads application locales before gems add their paths, ensuring your custom keys shadow the defaults appropriately.

Summary

• Ransack loads default translations from lib/ransack/locale/*.yml via lib/ransack/translate.rb lines 3-5.
• You can customize Ransack i18n translation files by adding YAML files to config/locales in your Rails application.
• Override keys for predicates, model names, attributes, and associations under the ransack namespace.
• Rails I18n precedence rules ensure your application translations shadow the gem's defaults.
• For advanced control, manually prepend your locale files to I18n.load_path in an initializer.

Frequently Asked Questions

Where are Ransack's default translation files located?

Ransack's default translation files are located in the lib/ransack/locale/ directory of the gem, with en.yml containing the English translations. These files are automatically added to the Rails I18n load path when the library initializes via the code in lib/ransack/translate.rb.

How do I change the search button text in Ransack?

To change the search button text, override the ransack.search key in your application's locale file. For example, add en.ransack.search: "Find records" to config/locales/ransack.yml. This will replace the default "Search" text in forms generated by Ransack's helpers.

Can I use custom translations for specific models only?

Yes, you can define model-specific translations using the ransack.models and ransack.attributes keys. For example, en.ransack.models.user: "Customer" and en.ransack.attributes.user.email: "Contact Email" will apply only to the User model, while other models continue using default or generic translations.

Do I need to restart the server after changing translations?

Yes, you must restart your Rails server after modifying YAML translation files in config/locales because Rails loads these files into memory at startup. Alternatively, in development mode, you can reload I18n by executing I18n.backend.reload! in the Rails console to pick up changes without a full restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}