Customizing Blacklight Tutorial Series (v5.14.0)

UI Labels (i18n)

Much of the text provided in the UI elements in Blacklight are customizable using rails’ internationalization (i18n). Blacklight has translations for its UI in 5 languages besides english. If you happen to find a piece of text that is provided by the Blacklight UI and not customizable via i18n please feel free to submit a pull request to fix it or file an issue in the issue tracker.

In order to override the values provided by Blacklight you need to add keys in your application’s locale YAML files (typically located in config/locales) for the languages that you would like to change. For this example, you’ll simply update the blacklight.en.yml file that was auto-generated into your application for you. If you’re developing a multi-lingual application you’ll also want to update the same key in Blacklight’s locale files for other languages.

The auto-generated blacklight.en.yml that is in your application has the application_name key that nearly every application will want to update. This key is used as the HTML title in the <head> section as well as various other places. If you change the application_name key your application will be updated with that value. Note that only the single key is auto-generated in that file. You only need to override the keys you want to change and do not need to copy the entire contents of the file.

    application_name: 'Blacklight'

In order to update other values you’ll need to determine which key to override. For example, if you wanted to update the placeholder text in the search box, instead of overriding the view you can simply find the i18n key and override it in your application’s blacklight.en.yml file.

Blacklight search box
Default placeholder text in search input

The partial for the search form is at app/views/catalog/_search_form.html.erb (GitHub). You can see that the placeholder attribute is t(''). This means that if we re-construct that key hierarchy in our blacklight.en.yml file our value will be used instead of the one in Blacklight.

          placeholder: 'Insert search terms here...'
Updated blacklight search box
Updated placeholder text in search input

You have now used rails’ internationalization library to make simple text updates to your Blacklight application without needing to override view partials.