Advanced topics

Using different locales

NILS can handle with different locales at a time. The NilsFactory provides access to different NLS objects.

nls() : Returns an NLS object of the default locale used by the JVM.
nls(Locale) : Returns an NLS object for a specific locale.
nls(String) : Returns an NLS object, where the locale is reolved by its language code.

Suppress errors

During development or testing it is useful to get exceptions if for example a translation is missing.

On a production system a more relaxed way is sometimes better for the end user instead of getting an error page because of a missing translation.

NILS provides therefore a way to suppress exceptions and errors. If NILS is configured to suppress errors and an error case has been occurred the user gets the escaped version of the requested translation (like '[Person.name]'). The error or exception that happened is logged via slf4j.

The NilsConfig provides with the method suppressErrors(boolean) a way to configure the behaviour.

The default is false, meaning all exception will not be suppressed.

Class name resolving

The NLS interface provides two methods using a Class as prefix for a translation key:

get(Class<?> key, String subKey)
get(Class<?> key, String subKey, Object… args)

The default behaviour is to use the simple name of a class. Therefore xyz.dummy.DummyClass will be DummyClass and a call of nls.get(DummyClass.class, "test") would be the translation key DummyClass.test.

How a class name is resolved is configurable in the NilsConfig using the method nilsConfig.classPrefixResolver(ClassPrefixResolver) by setting a ClassPrefixResolver implementation.

The NILS provides two implementations:

ClassPrefixResolver.SIMPLE_CLASSNAME : Using the simple name of a class (the default).
ClassPrefixResolver.FQN_CLASSNAME : Using the full qualified name of a class (xyz.dummy.DummyClass will be xyz.dummy.DummyClass).

But own resolver could be implemented and used.

Extending NILS

Writing your own adapter

If you need another kind of translation resource (as the existing ones) you can implement your own Adapter.

See Write your own adapter for more information.

Write a ClassPrefixResolver

If the existing Class-Prefix-Resolition doesn’t meet your requirements, you can write your own.

Implement the interface com.codepulsar.nils.core.handler.ClassPrefixResolver or use a lambda function and register your implementation in the method NilsConfig.classPrefixResolver(ClassPrefixResolver).

Write a TranslationFormatter

If the existing formatting of translation attributes doesn’t meet your requirements, you can write your own.

Implement the interface com.codepulsar.nils.core.handler.TranslationFormatter or use a lambda function and register your implementation in the method NilsConfig.translationFormatter(TranslationFormatter).

Error codes

NILS errors usually contains also an error code. Following the error codes are descripted with a possible solution.

Error code Description Hint

Error code	Description	Hint
NILS-001	The translation resource does not provide a translation for the requested key.	Add the translation or change the key.
NILS-002	Include of other keys leads into a loop.	Check your translation resources of a loop.
NILS-003	The parameter call at the NLS interface is invalid.	Check the error message for more information.
NILS-004	The configuration or a configuration value is invalid.	Check the error message for more information.
NILS-005	An error using an adapter occurred.	Check the error message for more information.
NILS-006	The value of a translation could not be formatted with the used TranslationFormatter.	Check if the translation contains an invalid format or if `{}` is used instead of `%` vice versa.
NILS-007	An error on IO level occurred (Maybe file access, network access etc.)	Check the error message for more information.
NILS-008	An requested resource file is missing (ResourceBundle).	Check the error message for more information.
NILS-009	A mandatory file extension is not found on a file name.	Check the file extension of the file name
*Error codes from Gson Adapter*
NILS-100	The used json file is corrupt	Check the json file for errors.
*Error codes from SnakeYaml Adapter*
NILS-150	The used yaml file is corrupt	Check the yaml file for errors.
*Error codes from Jackson Adapter*
NILS-200	A neccessary dependency (jar) is missing	Check if the mentioned jar file is added to the project. Maybe you use a yaml file, but have not added the jackson-yaml dependency.
NILS-201	The used json or yaml file is corrupt	Check the json or yaml file for errors.
*Error codes from JDBC Adapter*
NILS-250	The JDBC driver class name is invalid.	Check if the driver class name is correct.
NILS-251	Connection data contains invalid data for 'url' or 'username'.	Check of the JDBC URL and username is correct.
NILS-252	An SQLException occurred.	See the exeception cause for more information of the error.

NILS-001

The translation resource does not provide a translation for the requested key.

Add the translation or change the key.

NILS-002

Include of other keys leads into a loop.

Check your translation resources of a loop.

NILS-003

The parameter call at the NLS interface is invalid.