Jackson Adapter
This Adapter implementation uses the Jackson library to handle json
and yaml
files.
Use for JSON files
Add to your project
The easiest way to include NILS - Jackson Adapter is as dependency, if you use a build tool like Maven or Gradle.
You can find the current versions in the Maven central repository.
Maven:
<dependency>
<groupId>com.codepulsar.nils</groupId>
<artifactId>nils-jackson-adapter</artifactId>
<version>3.0.0</version>
</dependency>
Gradle:
implementation group: 'com.codepulsar.nils', name: 'nils-jackson-adapter', version: '3.0.0'
Using
After you have included the jar into your project you must create a NilsFactory
with a JacksonAdapterJsonConfig
to get access to the NLS support.
public class SimpleJacksonJsonExample extends BaseUI {
private static final NilsFactory NLS_FACTORY =
NilsFactory.init(JacksonAdapterJsonConfig.init(SimpleJacksonJsonExample.class)); (1)
@Override
protected void innerTranslate(
JLabel lblCustomerName, JLabel lblStreet, JLabel lblPageOf, JButton btnClose) {
NLS nls = NLS_FACTORY.nls(); (2)
lblCustomerName.setText(nls.get("customer.name")); (3)
lblStreet.setText(nls.get(Address.class, "street")); (4)
lblPageOf.setText(nls.get("page_counter", 3, 5)); (5)
btnClose.setText(nls.get("btn.close"));
}
// ...
1 | The example creates a NilsFactory using the JacksonAdapter. The JSON files "translation.json", "translation_en.json" etc. must be located in the same package as the class/object used in the init() -methods. |
2 | Get a new NLS object in the method you require the translation. |
3 | Get the translation for the key "customer.name" with no further arguments. |
4 | Get the translation by a Class and its attribute "street". |
5 | Get the translation for the key "page_counter" with two arguments. |
The corresponding JSON file com/codepulsar/nilsexamples/jacksonadapterjson/translation.json
could look like:
{
"customer": {
"name": "Name"
},
"Address": {
"street": "Street"
},
"btn": {
"close": "Close"
},
"page_counter": "Page {0} of {1}"
}
See also Advanced topics for more information how to configure NILS.
Include Translations
The adapter can also provides the inclusion of already defined keys, like it is possilbe for Resource Bundles.
A corresponding JSON file could look like:
{ "Person" : {
"surname" : "Surname",
"firstname" : "First name",
"birthday" : "Birthday"
},
"Employee" : {
"_include" : "Person", (1)
"surname" : "Family name" (2)
}
}
1 | This line include all keys from Person. If your application request for example Employee.firstname NILS will do a lookup and return the value from Person.firstname . |
2 | Employee overwrites the key for surname . So Employee.surname will return 'Family name' instead of 'Surname'. |
If you want to include more that one base you can add the values semicolon separated:
...
"Employee" : {
"_include" : "Person;com.myproject.BaseClass",
...
}
...
The ordering is important. The first look up will be taken on Person
. If 'Person' has no translation for the requested key, com.myproject.BaseClass
will be called next.
See also Include Translations
Configuration
Despite of the existing global configuration (see Advanced topics) the Jackson JSON Adapter configuration has the following additional configurations:
Disable fallback for translation resources
Per default if a translation key is not found in the current translation resource for a locale, the next translation resource will be used to resolve the requested key.
For example if your application has translation resources for "de_DE", "de" and one default, the fallback checks these resources in the given order.
So its possible to get a transalation in a different language as expected.
You can disable that fallback in the configuration:
var config = JacksonAdapterJsonConfig.init(SimpleJacksonJsonExample.class).fallbackActive(false);
var nilsFactory = NilsFactory.init(config);
Use for YAML files
Add to your project
The easiest way to include NILS - Jackson Adapter is as dependency, if you use a build tool like Maven or Gradle.
You can find the current versions in the Maven central repository.
Maven:
<dependency>
<groupId>com.codepulsar.nils</groupId>
<artifactId>nils-jackson-adapter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-yaml</artifactId>
<version>2.16.1</version>
</dependency>
Gradle:
implementation group: 'com.codepulsar.nils', name: 'nils-jackson-adapter', version: '3.0.0'
implementation group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-yaml', version: '2.16.1'
Using
After you have included the jar into your project you must create a NilsFactory
with a JacksonAdapterYamlConfig
to get access to the NLS support.
public class SimpleJacksonYamlExample extends BaseUI {
private static final NilsFactory NLS_FACTORY =
NilsFactory.init(JacksonAdapterYamlConfig.init(SimpleJacksonYamlExample.class)); (1)
@Override
protected void innerTranslate(
JLabel lblCustomerName, JLabel lblStreet, JLabel lblPageOf, JButton btnClose) {
NLS nls = NLS_FACTORY.nls(); (2)
lblCustomerName.setText(nls.get("customer.name")); (3)
lblStreet.setText(nls.get(Address.class, "street")); (4)
lblPageOf.setText(nls.get("page_counter", 3, 5)); (5)
btnClose.setText(nls.get("btn.close"));
}
// ...
1 | The example creates a NilsFactory using the JacksonAdapter. The YAML files "translation.yaml", "translation_en.yaml" etc. must be located in the same package as the class/object used in the init() -methods. |
2 | Get a new NLS object in the method you require the translation. |
3 | Get the translation for the key "customer.name" with no further arguments. |
4 | Get the translation by a Class and its attribute "street". |
5 | Get the translation for the key "page_counter" with two arguments. |
The corresponding YAML file com/codepulsar/nilsexamples/jacksonadapteryaml/translation.yaml
could look like:
customer:
name: Name
Address:
street: Street
btn:
close: Close
page_counter: Page {0} of {1}
See also Advanced topics for more information how to configure NILS.
Include Translations
The Adapter can also provides the inclusion of already defined keys, like it is possilbe for Resource Bundles.
A corresponding YAML file could look like:
Person:
surname: Surname
firstname: First name
birthday: Birthday
Employee:
_include: Person (1)
surname : Family name (2)
1 | This line include all keys from Person. If your application request for example Employee.firstname NILS will do a lookup and return the value from Person.firstname . |
2 | Employee overwrites the key for surname . So Employee.surname will return 'Family name' instead of 'Surname'. |
If you want to include more that one base you can add the values semicolon separated:
...
Employee:
_include : Person;com.myproject.BaseClass
...
The ordering is important. The first look up will be taken on Person
. If 'Person' has no translation for the requested key, com.myproject.BaseClass
will be called next.
See also Include Translations
Configuration
Despite of the existing global configuration (see Advanced topics) the Jackson YAML Adapter configuration has the following additional configurations:
Disable fallback for translation resources
Per default if a translation key is not found in the current translation resource for a locale, the next translation resource will be used to resolve the requested key.
For example if your application has translation resources for "de_DE", "de" and one default, the fallback checks these resources in the given order.
So its possible to get a transalation in a different language as expected.
You can disable that fallback in the configuration:
var config = JacksonAdapterYamlConfig.init(SimpleJacksonYamlExample.class).fallbackActive(false);
var nilsFactory = NilsFactory.init(config);