FormValidation v0.8.1 is released, supports Bootstrap 4 alpha 3

i18n add-on

Support defining messages in multiple languages

Add-ons

As you already knew, you can use the message option to indicate error message for each validator:

$(form).formValidation({
    fields: {
        userName: {
            validators: {
                notEmpty: {
                    message: '...'
                },
                stringLength: {
                    message: '...'
                }
            }
        }
    }
});

This i18n add-on allows to define messages in different languages. Below is a step by step instruction showing how to use the i18n add-on.

Including the add-on

  • Download the i18n add-on
  • Include i18n.min.js (located in the dist directory) to your page. Ensure that it's placed after formValidation(.min).js
<!-- FormValidation plugin -->
<script src="/vendor/formvalidation/dist/js/formValidation.min.js"></script>

<!-- Add-ons. You should place it inside /vendor/formvalidation/dist/js/addons directory -->
<script src="/vendor/formvalidation/dist/js/addons/i18n.min.js"></script>

Calling the add-on

It's possible to call the add-on in both programmatic and declarative ways:

$(form).formValidation({
    framework: '...',
    icon: {
        ...
    },
    addOns: {
        i18n: {}
    },
    fields: {
        ...
    }
});

If you want to use multiple add-ons, just simply separate them by a comma in data-fv-addons attribute:

data-fv-addons="i18n, mandatoryIcon, recaptcha2"

<form id="signUpForm" method="post" class="form-horizontal"
    data-fv-addons="i18n">
    ...
</form>

You even don't need to set any option for the i18n add-on.

Defining messages

The languages are distinguished by locales. A locale is combination of countrycode_LANGUAGECODE. Here countrycode and LANGUAGECODE are the ISO 3166 country and language codes in lowercase and uppercase respectively.

en_US (default), fr_FR, de_DE, vi_VN are some examples.

The i18n add-on provides three ways to define messages in different languages.

Using language packages

There are many supported language packages which provide the translation of default validator message in given language.

All of them are placed inside the js/language directory.

In order to use them, you only need to include the language file:

<script type="text/javascript" src="/vendor/formvalidation/dist/js/formValidation.js"></script>
<script type="text/javascript" src="/vendor/formvalidation/dist/js/framework/bootstrap.js"></script>

<!--
You can include many language packages as you want. Their order don't matter
as you ensure that they are loaded after formValidation(.min).js
-->
<script type="text/javascript" src="/vendor/formvalidation/dist/js/language/de_DE.js"></script>
<script type="text/javascript" src="/vendor/formvalidation/dist/js/language/fr_FR.js"></script>
<script type="text/javascript" src="/vendor/formvalidation/dist/js/language/vi_VN.js"></script>
It's not necessary to include the English package (en_US.js). It's default locale and the English messages are already included in the formValidation(.min).js file

Using literal object

By default, message must be a string. With the i18 add-on, you can use a Javascript literal object which maps the locale with associating message:

$(form).formValidation({
    fields: {
        fieldName: {
            validators: {
                validatorName: {
                    message: {
                        en_US: 'The message in English',
                        fr_FR: 'The message in French'
                    }
                }
            }
        }
    }
});

Using a callback function

You also can use a callback function that returns the literal object as above:

$(form).formValidation({
    fields: {
        fieldName: {
            validators: {
                validatorName: {
                    message: function(validator, $field, validatorName) {
                        // validator is the plugin instance
                        // $field is the field element
                        // validatorName is the name of current validator
                        return {
                            en_US: 'The message in English',
                            fr_FR: 'The message in French'
                        };
                    }
                }
            }
        }
    }
});

Switching languages

The previous section introduces various ways to define the message in different locales.

To switch messages between them (via a switcher control, for example), you need to call the setLocale() method:

// Switch messages to French
$(form).formValidation('setLocale', 'fr_FR');

Example

The following example uses all of three ways above to define the messages in different languages. It's up to you to choose any way in a multilingual website.

<!-- Include FormValidation files first -->

<!-- Then include mandatoryIcon add-on -->
<script src="/vendor/formvalidation/js/addons/i18n.min.js"></script>

<!-- Method 1: Include the language packages -->
<script src="/vendor/formvalidation/js/language/vi_VN.js"></script>
<script src="/vendor/formvalidation/js/language/fr_FR.js"></script>

<div class="row" style="margin-bottom: 15px;">
    <div class="col-xs-9 col-xs-offset-3">
        <!-- A simple locale switcher -->
        <div class="btn-group">
            <!-- The data-locale attribute will be used later -->
            <button type="button" class="btn btn-default active setLocaleButton" data-locale="en_US">English</button>
            <button type="button" class="btn btn-default setLocaleButton" data-locale="fr_FR">Français</button>
            <button type="button" class="btn btn-default setLocaleButton" data-locale="vi_VN">Tiếng Việt</button>
        </div>
    </div>
</div>

<form id="profileForm" method="post" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Username</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Email address</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="email" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Password</label>
        <div class="col-xs-5">
            <input type="password" class="form-control" name="password" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Gender</label>
        <div class="col-xs-5">
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="male" /> Male
                </label>
            </div>
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="female" /> Female
                </label>
            </div>
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="other" /> Other
                </label>
            </div>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Date of birth</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="birthday" placeholder="YYYY/MM/DD" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-9 col-xs-offset-3">
            <button type="submit" class="btn btn-default">Sign up</button>
        </div>
    </div>
</form>

<script type="text/javascript">
$(document).ready(function() {
    $('#profileForm').formValidation({
        framework: 'bootstrap',
        addOns: {
            i18n: {}
        },
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            // Since the messages of notEmpty, stringLength, regexp are not set here,
            // they will be taken from language package
            username: {
                validators: {
                    notEmpty: {
                    },
                    stringLength: {
                        min: 6,
                        max: 30,
                        // Method 2: Use a literal object to define messages
                        message: {
                            en_US: 'The username must be between %s and %s characters long',
                            vi_VN: 'Tên đăng nhập phải có ít nhất %s và nhiều nhất %s ký tự'
                        }
                    },
                    regexp: {
                        regexp: /^[a-zA-Z0-9]+$/
                    },
                    different: {
                        field: 'password',
                        // Method 2: Use a literal object to define messages
                        message: {
                            en_US: 'The username and password cannot be the same',
                            vi_VN: 'Mật khẩu và tên đăng nhập phải khác nhau'
                        }
                    }
                }
            },
            // Messages are taken from language package
            email: {
                validators: {
                    notEmpty: {
                    },
                    emailAddress: {
                    }
                }
            },
            // Messages of notEmpty and stringLength validators
            // are taken from language package
            password: {
                validators: {
                    notEmpty: {
                    },
                    stringLength: {
                        min: 8
                    },
                    different: {
                        field: 'username',
                        // Method 3: Use a callback to determine message in particular language
                        message: function(validator, $field, validatorName) {
                            return {
                                en_US: 'The password can\'t be same as username',
                                vi_VN: 'Mật khẩu phải khác tên đăng nhập'
                            };
                        }
                    }
                }
            },
            birthday: {
                validators: {
                    notEmpty: {
                    },
                    date: {
                        format: 'YYYY/MM/DD'
                    }
                }
            },
            gender: {
                validators: {
                    notEmpty: {
                    }
                }
            }
        }
    });

    $('.setLocaleButton').on('click', function() {
        $('.setLocaleButton').removeClass('active');
        $(this).addClass('active');

        // Change the locale
        $('#profileForm').formValidation('setLocale', $(this).attr('data-locale'));
    });
});
</script>

Change log

  • v0.1.1:

    • Fix the issue when using with validators supporting dynamic message such as the stringLength
  • v0.1.0: First release