Gson Adapter

This Adapter implementation uses the Gson library to handle json files.

Add to your project

The easiest way to include NILS - Gson 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-gson-adapter</artifactId>
  <version>3.0.0</version>
</dependency>

Gradle:

implementation group: 'com.codepulsar.nils', name: 'nils-gson-adapter', version: '3.0.0'

Using

After you have included the jar into your project you must create a NilsFactory with a GsonAdapterConfig to get access to the NLS support.

public class SimpleGsonExample extends BaseUI {

  private static final NilsFactory NLS_FACTORY =
      NilsFactory.init(GsonAdapterConfig.init(SimpleGsonExample.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"));
    lblPageOf.setText(nls.get("page_counter", 3, 5));
    btnClose.setText(nls.get("btn.close"));
  }

  public static void main(String[] args) {
    new SimpleGsonExample().show();
  }
}

1	The example creates a `NilsFactory` using the GsonAdapter. 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	Example call for the translation with the key "customer.name" with no arguments.

The corresponding JSON file com/codepulsar/nilsexamples/gsonadapter/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.

Configuration

Despite of the existing global configuration (see Advanced topics) the Gson 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 = GsonAdapterConfig.init(SimpleGsonExample.class).fallbackActive(false);
    var nilsFactory = NilsFactory.init(config);