L10n plugin

Support multiple locales for error messages

Usage

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

FormValidation.formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            userName: {
                validators: {
                    notEmpty: {
                        message: '...'
                    },
                    stringLength: {
                        message: '...'
                    },
                },
            },
            ...
        },
    }
);

This L10n plugin allows defining of messages in different languages. The following piece of code is the starting point to use the L10n plugin:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="demoForm" method="POST">...</form>

        <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
        <script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
        <script src="/vendors/@form-validation/umd/plugin-l10n/index.min.js"></script>

        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('demoForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            l10n: new FormValidation.plugins.L10n({
                                // Replace FIELD_NAME and VALIDATOR_NAME with real names
                                FIELD_NAME: {
                                    VALIDATOR_NAME: ...,
                                },
                            }),
                            ...
                        },
                    }
                );
            });
        </script>
    </body>
</html>

The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Defining messages

The languages are distinguished by locales. A locale is a 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 L10n plugin provides three ways to define messages in different languages.

1. Using language packages

There are many supported language packages that provide the translation of default validator messages in a given language. In order to use them, you only need to include the language file:

<script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>

<!--
You can include many language packages as you want. Their order doesn't matter
as you ensure that they are loaded after `bundle/popular.min.js`
-->
<script src="/vendors/@form-validation/umd/locales/en_US.min.js"></script>
<script src="/vendors/@form-validation/umd/locales/fr_FR.min.js"></script>
<script src="/vendors/@form-validation/umd/locales/vi_VN.min.js"></script>

2. Using literal object

Map the locale with associating message for a particular validator:

plugins: {
    ...
    l10n: new FormValidation.plugins.L10n({
        username: {
            stringLength: {
                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ự',
            },
        },
    }),
}

3. Using a callback function

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

plugins: {
    ...
    l10n: new FormValidation.plugins.L10n({
        password: {
            stringLength: function(field, validator) {
                // field is the field name
                // validator the name of the current validator
                return {
                    en_US: 'The password must have at least %s characters',
                    vi_VN: 'Mật khẩu phải có ít nhất %s ký tự',
                };
            },
        },
    }),
}

Switching locales

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:

<!-- To switch between locales. The data-locale attribute will be used later -->
<button type="button" class="setLocaleButton" data-locale="en_US">English</button>
<button type="button" class="setLocaleButton" data-locale="vi_VN">Tiếng Việt</button>

<script>
    document.addEventListener('DOMContentLoaded', function(e) {
        const fv = FormValidation.formValidation(
            document.getElementById('demoForm'),
            {
                // Set the default locale
                locale: 'en_US',
                localization: FormValidation.locales.en_US,

                fields: {
                    ...
                },
                plugins: {
                    l10n: new FormValidation.plugins.L10n({
                        ...
                    }),
                    ...
                },
            }
        );

        // Find all buttons that can change the locale
        const localeButtons = Array.from(document.querySelectorAll('.setLocaleButton'));
        localeButtons.forEach(function(btn) {
            btn.addEventListener('click', function() {
                // Get the associate locale from data-locale attribute
                const locale = btn.getAttribute('data-locale');

                // Change the locale
                fv.setLocale(locale, FormValidation.locales[locale])
                  .resetForm();
            });
        });
    });
</script>

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.

Install the packages:

$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-l10n

Import and use the L10n plugin:

import { formValidation } from '@form-validation/bundle/popular';
import { L10n } from '@form-validation/plugin-l10n';

formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            ...
        },
        plugins: {
            l10n: new L10n({
                ...
            }),
            ...
        },
    }
);

Basic example

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

L10n plugin

Changelog

v2.4.0

The plugin can be enabled or disabled using the enablePlugin and disablePlugin methods

v2.0.0

Add the npm package

v1.6.0

Supported localized error messages in custom validator

const strongPassword = function() {
    return {
        validate: function(input) {
            const value = input.value;
            if (value === '') {
                return {
                    valid: true,
                };
            }

            if (value.length < 8) {
                return {
                    valid: false,
                    message: {
                        en_US: 'The password must have at least 8 characters',
                        vi_VN: 'Mật khẩu phải có ít nhất 8 ký tự',
                    },
                };
            }

            ...
        }
    };
};

v1.0.0

First release

J plugin Mailgun plugin

L10n plugin

Usage

Defining messages

Switching locales

Using the npm packages

Basic example

See also

Changelog