How to handle translations in AutoForm-based forms [Meteor's Simple Schema]

In one of the projects I’ve been recently working on, I needed i18n support for forms generated with AutoForm. For those who don’t know: Autoform is a schema-based form generator. Since Meteor forms and ecosystem aren’t mature yet, this turned out to be an interesting task which ended up with creating a new package that we’ve published for the benefit of the Meteor community.

Jan Wieczorkowski

January 11, 2016 • 7 min read

In one of the projects I've been recently working on I needed i18n support for forms generated with AutoForm.

For those who don’t know: Autoform is schema-based form generator. Since Meteor ecosystem ain’t mature yet, this turned out to be an interesting task which ended up with creating a new package that we’ve published for the benefit of the Meteor community.

To give you more detailed information on post contents:

You’ll start with creating a simple Meteor application and adding translations (tap:i18n package)
Next you’ll take care of labels and error messages translations. There are two ways here:
- First which utilizes tap:i18n and naturaily:simple-schema-translations packages. You'll find detailed instructions in Readme file in Naturaily's package
- Second which utilizes tap:i18n and some additional coding
Finally you’ll take care of displaying server-side error messages

What you will need to install:

Meteor - JavaScript platform for building web and mobile apps. You probably have it on your machine
AutoForm - Meteor package for schema-based form generation

OK, let’s start.

Sample application without translations

Create a simple application that utilizes AutoForm for custom login and signup forms. Follow the steps below or just copy the code from repo.

Get Meteor
Create a new application meteor create myAwesomeApp
Install AutoForm meteor add aldeed:autoform
Add a user account system with password support meteor add accounts-password
Add bootstrap (app will look a bit better) meteor add twbs:bootstrap

Create LoginSchema and RegistrationSchema. Firstly, clear *.js file. Next, add the code below:

1  LoginSchema = new SimpleSchema({
2    login: {
3      type: String
4    },
5    password: {
6      type: String,
7      autoform: {
8        afFieldInput: {
9          type: 'password'
10        }
11      }
12    }
13  });
14
15  RegistrationSchema = new SimpleSchema({
16    username: {
17      type: String
18    },
19    email: {
20      type: String,
21      regEx: SimpleSchema.RegEx.Email
22    },
23    password: {
24      type: String,
25      autoform: {
26        afFieldInput: {
27          type: 'password'
28        }
29      }
30    },
31    passwordConfirmation: {
32      type: String,
33      autoform: {
34        afFieldInput: {
35          type: 'password'
36        }
37      },
38      custom: function() {
39        if (this.isSet && this.value !== this.field('password').value) {
40          return 'invalidPasswordConfirmation';
41        }
42      }
43    }
44  });

tsx

Change default templates. Your *.html file should look like this one:

1  <head>
2    <title>meteortranslations</title>
3  </head>
4
5  <body>
6    <div class="container">
7      <h1>Welcome to Meteor!</h1>
8      {% raw %}
9      {{#if currentUser}}
10        {{> forLoggedIn}}
11      {{else}}
12        {{> forLoggedOut}}
13      {{/if}}
14      {% endraw %}
15    </div>
16  </body>
17
18  <template name="forLoggedIn">
19    <a id="logout" href="#" class="btn btn-default">
20      logout
21    </a>
22  </template>
23
24  <template name="forLoggedOut">
25    <h2>Sign in</h2>
26    {% raw %}
27      {{> quickForm id="signInForm" schema="LoginSchema"}}
28    {% endraw %}
29
30    <h2>Sign up</h2>
31    {% raw %}
32    {{> quickForm id="signUpForm" schema="RegistrationSchema"}}
33    {% endraw %}
34  </template>

tsx

Events handlers. Also we need to handle forms and logout button events. So add the code below to your *.js file:

1  if (Meteor.isClient) {
2    AutoForm.hooks({
3      signUpForm: {
4        onSubmit: function(data) {
5          this.event.preventDefault();
6          Accounts.createUser(data, this.done);
7        }
8      },
9      signInForm: {
10        onSubmit: function(data) {
11          this.event.preventDefault();
12          Meteor.loginWithPassword(data.login, data.password, this.done);
13        }
14      }
15    });
16
17    Template.forLoggedIn.events({
18      'click #logout': function (e) {
19        e.preventDefault();
20        Meteor.logout();
21      }
22    });
23  }

tsx

Remove *.css file. We don't need this right now. Aaand done! We have a sample app :)

Add translations

From a few i18n packages available I chose tap:i18n. It’s not a requirement, but if you’ll choose a different package you won’t be able to use naturaily:simple-schema-translations.

Add tap:i18n meteor add tap:i18n
Add tap:i18n-ui meteor add tap:i18n-ui
Create i18n directory mkdir i18n

Create files with translations (english and polish in my case)

1  // i18n/en.i18n.json
2  {
3    "title" : "Welcome to Meteor!",
4    "signUp" : "Sign up",
5    "signIn" : "Sign in",
6    "logout" : "logout"
7  }
8
9  // i18n/pl.i18n.json
10  {
11    "title" : "Witaj!",
12    "signUp" : "Zarejestruj sie",
13    "signIn" : "Zaloguj sie",
14    "logout" : "Wyloguj sie"
15  }

tsx

Use translations in your HTML file. Replace

1  <h1>Welcome to Meteor!</h1>
2
3  <a id="logout" href="#">
4    logout
5  </a>
6
7  <h2>Sign in</h2>
8
9  <h2>Sign up</h2>

tsx

with

1  <h1>{% raw %}{{_ 'title'}}{% endraw %}</h1>
2
3  <a id="logout" href="#">
4  {% raw %}{{_ 'logout'}}{% endraw %}
5  </a>
6
7  <h2>{% raw %}{{_ 'signIn'}}{% endraw %}</h2>
8
9  <h2>{% raw %}{{_ 'signUp'}}{% endraw %}</h2>

tsx

Add a dropdown <select> list of available languages. Paste the code below after h1 tag:
{% raw %}{{> i18n_dropdown}}{% endraw %}

And now you can change language on your site. Check it out!

Translate labels and error messages

OK, all happy now? Not really… There are still English labels and error messages that we need to handle somehow. We have two options here, as mentioned before:

Use naturaily:simple-schema-translations if you decided to utlizie tap:i18n earlier
Handle translations on your own, with two options for labels and one for error messages. This will work with tap:i18n or any other reactive translations library

Translate labels

First approach - simple, universal, with code repeats

Just use label option in your schema and use your translation library:

1  LoginSchema = new SimpleSchema({
2    login: {
3      type: String,
4      label: function() {
5        YourLibrary.translate('key');
6      }
7    },
8  //...
9  })

tsx

Some libraries need to receive language key on the server:

1  label: function () {
2    if (Meteor.isClient) {
3      YourLibrary.translate('key');
4    } else if (Meteor.isServer) {
5      YourLibrary.translate('key', 'en');
6    }
7  }

tsx

Second approach - fancy, DRY, all schemas in one namespace

We want to use function labels from aldeed:simple-schema. In this example I will use tap:i18n but you can use any reactive translation library. Firstly, we will need a namespace for all our schemas.

1  Schemas = {
2    LoginSchema: new SimpleSchema({
3      //...
4    }),
5    RegistrationSchema: new SimpleSchema({
6      //...
7    })
8  };

tsx

Next, we have to add some translations:

1  {
2    //...
3    "labels" : {
4      //...
5      "login" : "Nazwa uzytkownika lub email",
6      "password" : "Haslo",
7      "passwordConfirmation" : "Powtorz haslo"
8    }
9  }

tsx

Next, we need something like this:

1  if (Meteor.isClient) {
2    Meteor.startup(function () {
3      // TAPi18n.__ returns key instead of object by default
4      TAPi18next.init({
5        objectTreeKeyHandler: function (key, value) {
6          return value;
7        }
8      });
9  
10      Tracker.autorun(function () {
11        translateLabels(TAPi18n.__("labels"));
12      });
13    });
14  }

tsx

As you can see translateLabels function will be invoked each time when language will be changed. And now we have to implement this function :) We need to remember that SimpleSchema needs empty string to set default label.

1  function translateLabels(labels) {
2    Schemas.forEach(function (schema) {
3      var labelsWithDefaults = _.tap({}, function(object) {
4        schema._schemaKeys.forEach(function(key) {
5          object[key] = labels[key] || '';
6        });
7      });
8      schema.labels(labelsWithDefaults);
9    });
10  }

tsx

And that's it!

Translate error messages

This one’s pretty easy. Just cache default messages and change global messages every time language is changed.

1  if (Meteor.isClient) {
2    Meteor.startup(function () {
3      var defaultMessages = _.clone(SimpleSchema._globalMessages);
4  
5      Tracker.autorun(function () {
6        function translateErrorMessages(translations) {
7          var messages = _.extend({}, defaultMessages, translations);
8          SimpleSchema.messages(messages);
9        }(TAPi18n.__("errors"));
10      })
11    })
12  }

tsx

Translate and display server-side error messages

Server-side error messages are handled separately thanks to hooks provided by AutoForm. You can use onError hook to catch server error and add it to the form.

1  if (Meteor.isClient) {
2    // I think that this function explains itself :)
3    function parseError(error) {
4      var errors = {
5        'User not found': [
6          {
7            name: 'login',
8            type: 'incorrect'
9          }
10        ],
11        'Incorrect password': [
12          {
13            name: 'password',
14            type: 'incorrect'
15          }
16        ],
17        'Username already exists.': [
18          {
19            name: 'username',
20            type: 'taken'
21          }
22        ],
23        'Email already exists.': [
24          {
25            name: 'email',
26            type: 'taken'
27          }
28        ]
29      };
30  
31      return errors[error.reason];
32    }
33    // add hooks to every form generated by AutoForm
34    AutoForm.addHooks(null, {
35      onError: function (e, error) {
36        var errors = parseError(error);
37
38        if (errors) {
39          var names = _.map(errors, function(error) {
40            return error.name;
41          });
42  
43          errors.forEach(function(error) {
44            this.addStickyValidationError(error.name, error.type);
45          }.bind(this));
46
47          this.template.$('form').on('input', 'input', function(event) {
48            var name = event.target.name;
49  
50            if (_.contains(names, name)) {
51              this.removeStickyValidationError(name);
52            }
53          }.bind(this));
54        }
55      }
56    });
57  }

tsx

As you can see I use addStickyValidationError instead of non-sticky errors. Why? Because form is often revalidated and then custom errors will disappear. It's annoying. Really.