Form.io Translations

Introduction

Formio.js uses i18n, a lightweight translation module, which allow users to pass in a translation option during form construction. This gives users direct control over several form settings such as:

  • Setting a form’s default language
  • Changing a form’s default error messages
  • Defining a form’s default language behaviour
  • Translating a form’s custom message object that was defined in the JSON definition

The guide that follows illustrates how to leverage this module in any application, regardless of framework preference.

Source Code

A demo of this application and affiliate source code is available online. We encourage you to walk through the full guide, but if you would like to have this application up and running quickly, hen feel free to run the application from the source code. You can also use the source code as a reference when walking through this tutorial. Click on the button below to download the source code for this application.

Application Setup

Since the translations of Form.io elements are handled by our core library, the implementation can be executed via pure javascript. Below is as an example of a bare-bones use case of our core renderer that we’ll be adding code to throughout this walk through.

The Objective

The Objective of this walk through is to not only translate all the labels, and placeholders within the form, but also the system error messages. Clicking the Submit button without entering any data into the fields will result in the following error messages:

  • Primary Error Dialog
  • Please fix the following errors before submitting.
    • First Name is required
    • Last Name is required
  • Below Input Fields
  • First Name is required
  • Last Name is required
  • Below Submit Button
  • Please fix the following errors before submitting.

Going Remote

To prevent the form definition from dominating the javascript page, we will be converting the current RAW component definition into a remote project string hosted on Form.io’s Portal. Feel free to visit the URL in the Formio.createForm method to view, copy, or import the current form definition or download the project.json directly.

Now that we are leveraging the portal’s form builder, we can add more elements to the application without having to spend time hard coding each property directly. In this example, a panel element has been added to the form to help visual distinguish the form inputs from the buttons that we will be adding momentarily.

Adding Button Events

Adding an interface to toggle the between the languages has been added via a separate panel with 3 buttons. Each button has had the Action property switched to Event, and the Button Event property set to toggle'lng'.

With the form configured, take a look at the javascript of the third and final section.

Notice the two properties added during the Formio.createForm method: language and i18n. the language property can be used to set form’s default language at the time of construction, while the i18n property accepts an object that can be used to set translations during form’s creation. In this demo we’ve changed the english default for the Submit button to read Complete. To learn more about these properties and other options, please reference this section of the formio.js library.

As for actually changing languages, the buttons, since they have a unique event handlers, can be configured via the form events section that has been left blank until this point. to learn more about button events and please reference this section of the formio.js library.

Helpful Tools

As a quick reference here is a list of some default error message properties. Notice that in above example, the required : "{{field}} is required" message was able to be translated into other languages while preserving the bracket notation.

{
  "error" : "Please fix the following errors before submitting.",
  "invalid_date" :"{{field}} is not a valid date.",
  "invalid_email" : "{{field}} must be a valid email.",
  "invalid_regex" : "{{field}} does not match the pattern {{regex}}.",
  "mask" : "{{field}} does not match the mask.",
  "max" : "{{field}} cannot be greater than {{max}}.",
  "maxLength" : "{{field}} must be shorter than {{length}} characters.",
  "min" : "{{field}} cannot be less than {{min}}.",
  "minLength" : "{{field}} must be longer than {{length}} characters.",
  "next" : "Next",
  "pattern" : "{{field}} does not match the pattern {{pattern}}",
  "previous" : "Previous",
  "required" : "{{field}} is required"
}

For a complete list of all Form.io defaults, please reference the i18n.json file in the formio.js library.