# How to Customize Ransack i18n Translation Files: A Complete Guide

> Learn to customize Ransack i18n translation files easily by adding YAML to your Rails config locales. Override defaults and enhance your search experience with this complete guide.

- Repository: [ActiveRecord Hackery/ransack](https://github.com/activerecord-hackery/ransack)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/activerecord-hackery/ransack/blob/main/lib/ransack/translate.rb), lines 3-5, the library appends its locale directory to `I18n.load_path`:

```ruby

# 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`](https://github.com/activerecord-hackery/ransack/blob/main/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:

```yaml

# 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`:

```yaml

# 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:

```yaml

# 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:

```ruby

# 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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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.