Internationalization

Introduction

The messages that are shown when a validation fails can be customized in different ways. Due to the fact that there are different types of validations possible (like JSF based validators, BeanValidation based, ExtVal powered, and so on) it can be sometimes a bit confusing what needs to be done to change a certain text. This page gives an easy way to customize the messages.

Message bundle keys

Just like most web applications, the messages are identified by keys of resource bundles. The following table gives an overview of the keys:

ExtVal annotations

annotation

resource bundle key

@Required

field_required

@Length

javax.faces.validator.LengthValidator.MINIMUM
javax.faces.validator.LengthValidator.MAXIMUM

@Pattern

no_match

@LongRange

javax.faces.validator.LongRangeValidator.NOT_IN_RANGE
javax.faces.validator.LongRangeValidator.MAXIMUM
javax.faces.validator.LongRangeValidator.MINIMUM
javax.faces.validator.LongRangeValidator.TYPE

@DoubleRange

javax.faces.validator.DoubleRangeValidator.NOT_IN_RANGE
javax.faces.validator.DoubleRangeValidator.MAXIMUM
javax.faces.validator.DoubleRangeValidator.MINIMUM
javax.faces.validator.DoubleRangeValidator.TYPE

JPA annotations

annotation

resource bundle key

@Column
@Basic
@Id
@OneToOne
@ManyToOne

field_required
field_too_long

ExtVal Crossvalidation annotations

annotation

resource bundle key

@Equals

duplicated_content_required

@NotEquals

duplicated_content_denied

@DateIs

wrong_date_not_before
wrong_date_not_after
wrong_date_not_equal

@RequiredIf

empty_field

@EmptyIf

field_not_empty

BeanValidation annotations

The key which is used, can be constructed using the annotation name. The pattern is javax.validation.constraints.'xxx'.message where xxx is the annotation name.

So the resource bundle key for the @Null annotation is javax.validation.constraints.Null.message

For completeness, this is the list of known annotations : @AssertFalse, @AssertTrue, @DecimalMax, @DecimalMin, @Digits, @Future, @Max, @Min, @NotNull, @Null, @Past, @Pattern, @Size

Define Resource Bundle

In the above list you can see that there are 4 groups of annotations that can be used by ExtVal to do validations. The validation strategies (the code that is responsible for making the actuals checks) for the ExtVal annotations can be split up into 2 groups. The ones that uses the JSF Validators (like @Length) and those that are implmented by ExtVal itself (like @Pattern and @Required). So we have actually 5 groups that have small differences in 'resolving' their message. You can find the details in the next paragrapgh, but if you need a quick solution that works for any group, do the following:

  1. Make a new resource bundle, according to the standards of Java (a properties files with the correct postfixes for the languages and countries). An example could be com/mycompany/myprog/messages.properties, com/mycompany/myprog/messages_NL.properties, etc ..
  2. Define this resource bundle as message bundle in your faces-config file
    <application>
    <message-bundle>com.mycompany.myprog.messages</message-bundle>
    </application>

  3. Define the following web application parameters in your web.xml file.
    <context-param>
    <param-name>org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE</param-name>
    <param-value>com.mycompany.myprog.messages</param-value>
    </context-param>
    <context-param>
    <param-name>org.apache.myfaces.extensions.validator.JPA_VALIDATION_ERROR_MESSAGES</param-name>
    <param-value>com.mycompany.myprog.messages</param-value>
    </context-param>

You now can use the keys listed in first section of this page to redefine the message you like to see when the validation fails. It is best that you also add the key with the postfix _detail to this custom resource bundle, because otherwise it is possible that the message isn't taken (although the detail message isn't used from JSF 1.2 anymore)

If you like to use other keys then the ones on this page, you can specify them with the property validationErrorMsgKey (non BeanValidation annotations) or messages (BeanValidation annotations) except for the JPA annotations and the annotations that uses a JSF validator (@Length, @LongRange and @DoubleRange)

Detailed customization steps

In this paragrapgh, the different steps which are followed to resolve the message are written out for each of the 5 groups. This can be used if you want to customize the Internationalization aspect of ExtVal further more.

See also on the advanced Internationalization page (TODO) for some examples that uses some of these aspects.

MessageResolver

MessageResolver is the interface that needs to be implemented when ExtVal is responsible for looking up the message of the validation message. (See ... TODO)

ExtVal annotation that isn't using a JSF Validator

These are the steps that are followed when a validation error occurs linked to the @Required and @Pattern annotation.

The text or the key of the resource bundle specified in the property validationErrorMsgKey of the annotation will be used to lookup the message. If the user didn't specify one, the default one is used and can be found in the table on top of the page. The value of it will be referenced as msgOrKey in the rest of the paragraph.

  1. When the msgOrKey value contain a space, it is the literal text that is used as message.

  2. The value of msgOrKey is used as the key of the resource bundle which is injected into the messageResolver properties messageBundleBaseName or messageBundleVarName. If found, this message is used.

  3. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.custom.validation_messages use this on.

  4. if msgOrKey found in resource bundle specified as parameter org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE in web.xml use this one.

  5. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.baseval.message.bundle.validation_messages use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)

  6. Use the default message (key javax.faces.component.UIInput.REQUIRED) from the resource bundle specified in the faces-config in case of a @Required annotation validation.

ExtVal annotation that is using a JSF Validator

The message is resolved througgh the standard functionality of JSF. This means that the JSF keys (javax.faces.validator.xxxx) are looked up first in the message bundle defined in the faces-config file. If it can't find it there, it looks in the default bundle of the system where they are always present.

So ExtVal isn't responsible for resolving the message.

JPA annotations

The keys used (as value for msgOrKey) is field_reqiured or field_too_long.

  1. When the msgOrKey value contain a space, it is the literal text that is used as message. This can only be achieved by using some add-on that uses the Virtual metadata add-on to change the value.

  2. The value of msgOrKey is used as the key of the resource bundle which is injected into the messageResolver properties messageBundleBaseName or messageBundleVarName. If found, this message is used.

  3. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.custom.validation_messages use this on.

  4. if msgOrKey found in resource bundle specified as parameter org.apache.myfaces.extensions.validator.JPA_VALIDATION_ERROR_MESSAGES in web.xml use this one.

  5. When a resourcebundle is specified in the global property JPA_VALIDATION_ERROR_MESSAGES and the key is found there, use that one.

  6. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.baseval.message.bundle.validation_messages use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)

  7. Use the default message (key javax.faces.component.UIInput.REQUIRED or javax.faces.validator.LengthValidator.MAXIMUM, depending on the violation found)) from the resource bundle specified in the faces-config.

Cross validation annotations

The text or the key of the resource bundle specified in the property validationErrorMsgKey of the annotation will be used to lookup the message. If the user didn't specify one, the default one is used and can be found in the table on top of the page. The value of it will be referenced as msgOrKey in the rest of the paragraph.

  1. When the msgOrKey value contain a space, it is the literal text that is used as message.

  2. The value of msgOrKey is used as the key of the resource bundle which is injected into the messageResolver properties messageBundleBaseName or messageBundleVarName. If found, this message is used.

  3. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.custom.validation_messages use this on.

  4. if msgOrKey found in resource bundle specified as parameter org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE in web.xml use this one.

  5. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.crossval.message.bundle.validation_messages use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)

Bean validation

The validations performed by the Bean Validation Framework are based on a completely different system then the ones by JSF itself. No exception with a message is thrown but a list of problems is returned. However, they have forseen a pluggable mechanism for the messages, the MessageInterpolator. ExtVal suplies a bridge to the MessageResolver system of ExtVal which results in a almost identical list of posibilities.

The message for the validation message is based on the text/resource key of the property message. An important remark is that all keys (and messages) should be enclosed by curly brackets ({ and }) to go through the ExtValAdapter that allows the usage of the MessageResolver.

  1. When the msgOrKey value contain a space, it is the literal text that is used as message.

  2. The value of msgOrKey is used as the key of the resource bundle which is injected into the messageResolver properties messageBundleBaseName or messageBundleVarName. If found, this message is used.

  3. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.custom.validation_messages use this on.

  4. if msgOrKey found in resource bundle specified as parameter org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE in web.xml use this one.

  5. if msgOrKey found in resource bundle org.apache.myfaces.extensions.validator.core.message.bundle.validation_messages use this one. But this resource bundle isn't avalaible by default. It can be specified by the user.

When no curly braces are specified, the adapter is not used and you have only the default functionality of BV. If the resource key doesn't exist in the resource bundle ValidationMessages or default implemntation resource bundle like org.hibernate.validator.ValidationMessages, you get the value itself (and it is supposed to be the error message)

Extensions/Validator/I18N (last edited 2010-07-05 09:53:09 by RudyDeBusscher)