Introduction

NILS is a lightweight Java library for NLS (aka "national language support", "localization", "internationalization", "i18n", "l10n").

The library enables developers to integrate NLS into their Java projects easily.

Despite the fact that NILS provides a simple API for accessing translations, it also providex some adapters for different translation resources:

Adapter Resource type Maven Dependency

Part of nils-core

*.properties

 
<dependency>
  <groupId>com.codepulsar.nils</groupId>
  <artifactId>nils-core</artifactId>
  <version>1.4.0</version>
</dependency>

Gson Adapter

*.json

 
<dependency>
  <groupId>com.codepulsar.nils</groupId>
  <artifactId>nils-gson-adapter</artifactId>
  <version>1.4.0</version>
</dependency>

Jackson Adapter

.json, .yaml

 
<dependency>
  <groupId>com.codepulsar.nils</groupId>
  <artifactId>nils-jackson-adapter</artifactId>
  <version>1.4.0</version>
</dependency>

SnakeYaml Adapter

*.yaml

 
<dependency>
  <groupId>com.codepulsar.nils</groupId>
  <artifactId>nils-snakeyaml-adapter</artifactId>
  <version>1.4.0</version>
</dependency>

It can also be extended with own adapter implementations. See Writing your own adapter for more information.

Getting started

Requirements

The library requires

  • Java 11 or higher.

  • The SLF4J Api for logging.

Existings adapters can depend on more libraries. These dependencies are included transitive, if you use a build tool.

Add to your project

The following examples uses Resource bundles provided by nils-core.

The easiest way to include NILS 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-core</artifactId>
  <version>1.4.0</version>
</dependency>

Gradle:

implementation group: 'com.codepulsar.nils', name: 'nils-core', version: '1.4.0'

Using

After you have included the dependency to your project you must create a NilsFactory to get access to the NLS support.

Following a simple example.

public class SimpleUse {

  private static final NilsFactory NLS_FACTORY =
      NilsFactory.init(ResourceBundleAdapterConfig.init(SimpleUse.class)); (1)

  ...

  public void translate() {
    var nls = NLS_FACTORY.nls(); (2)

    var customerName = nls.get("customer.name"); (3)
    var pageXOfY = nls.get("page_counter", 3, 5); (4)
    var street = nls.get(Address.class, "street"); (5)
  }
}
1 The example creates a NilsFactory using resource bundles located at "nls/translation.properties".
2 Get a new NLS object for the default Locale of the running JVM.
3 Get the translation for the key "customer.name" with no further arguments.
4 Get the translation for the key "page_counter" with two arguments.
5 Get the translation by a Class and its attribute "street".

Following the correspoding file nls/translation.properties:

See also Advanced topics for more information how to configure NILS.

customer.name=Customer name
page_counter=Page {0} of {1}
Address.street=Street

The next example shows how to use NLS for a specific locale (in this case German).

public class SimpleUse {

  private static final NLS NLS_DE =
      NilsFactory.init(ResourceBundleAdapterConfig.init(SimpleUse.class))
        .nls(Locale.GERMAN); (1)

  ...

  public void translateDE() {
    var customerName = NLS_DE.get("customer.name");
    var pageXOfY = NLS_DE.get("page_counter", 3, 5);
    var street = NLS_DE.get(Address.class, "street");
  }
}
1 Call of the NilsFactory for the Locale.GERMAN.

The corresponding resource nls/translation_de-DE.properties could be:

customer.name=Kundenname
page_counter=Seite {0} von {1}
Address.street=Straße