Skip to main content

This is a guide on using the GOV.UK Design System Form Builder

  1. Index
  2. Localisation

Localisation

The simplest way of adding textual information like labels and hints to forms is to provide strings as arguments to the form helpers.

= f.govuk_text_field :name, label: { text: "Your full name" }

On larger, more-complex projects, copy is spread throughout the application and often duplicated, making it difficult for content designers to make changes.

Many teams approach this problem by making use of Rails’ excellent localisation functionality, allowing text to be stored in locale dictionaries. This allows editors to make changes without the risk of breaking templates and having to learn templating languages and hunt down content.

Populating label and hint text from the localisation data

Note that despite the text attribute being omitted from the label options hash, the other display and formatting parameters can be supplied and work in the normal manner.

Localisation data

helpers:
  label:
    person:
      favourite_kind_of_hat: Which style of hat do you prefer?
  hint:
    person:
      favourite_kind_of_hat: |-
        Trilby, Stetson, Deerstalker, Fez, Top and Beret are
        the most-fashionable

Input

= f.govuk_text_field :favourite_kind_of_hat, label: { size: 'm' }

Rendered output

Trilby, Stetson, Deerstalker, Fez, Top and Beret are the most-fashionable

HTML output

<div class="govuk-form-group">
  <label for="person-favourite-kind-of-hat-field" class="govuk-label govuk-label--m">
    Which style of hat do you prefer?
  </label>
  <span class="govuk-hint" id="person-favourite-kind-of-hat-hint">
    Trilby, Stetson, Deerstalker, Fez, Top and Beret are
    the most-fashionable
  </span>
  <input id="person-favourite-kind-of-hat-field" class="govuk-input" type="text" name="person[favourite_kind_of_hat]" />
</div>

Customising locale structure

There are many approaches to organising localisation data and while the default will work for most projects, sometimes a different approach can be beneficial. This is especially true when working with external localisation agencies or when dealing with large volumes of copy.

To customise the location of our localisation strings, we can configure the schema as part of the application’s initialisation process.

Contexts

There are three contexts supported by the form builder: label, legend and hint. Custom locale schemas are configured using an array of symbols that match your locale structure.

The special value __context__ is used to represent the current translation context. It will automatically be replaced with either label, legend or hint when the translation key is generated.

When retrieving a localised string the builder first checks whether a contextual schema has been set for the context. If there hasn’t, the localisation_schema_fallback key will be used. It is the only one set by default.

Configuration

Place your configuration in an initializer to ensure it’s loaded every time you start your Rails application.
GOVUKDesignSystemFormBuilder.configure do |conf|
  conf.localisation_schema_fallback = %i(helpers __context__)
  conf.localisation_schema_hint     = %i(copy descriptions __context__ subdivision)
end

Localisation data

helpers:
  label:
    person:
      role: What role do you play?

copy:
  descriptions:
    hint:
      subdivision:
        person:
          role: |-
            Roles may be achieved or ascribed or they can be accidental
            in different situations. An achieved role is a position
            that a person assumes voluntarily which reflects personal
            skills, abilities, and effort.

Input

= f.govuk_text_field :role, label: { size: 'm' }

Rendered output

Roles may be achieved or ascribed or they can be accidental in different situations. An achieved role is a position that a person assumes voluntarily which reflects personal skills, abilities, and effort.