Skip to content
This repository has been archived by the owner on Nov 15, 2020. It is now read-only.

Quick Start

Jump to bottom
Matthias Ngeo edited this page Mar 6, 2019 · 14 revisions

1. Adding Lingua Franca as a dependency

releases-maven snapshots-maven

Lingua Franca 1.0.2 and above requires Java 11; prior versions require Java 10.

1.1. Maven

<!-- Release Builds -->
<repository>
  <id>lingua-releases</id>
  <url>https://repo.karuslabs.com/repository/lingua-franca-releases/</url>
</repository>

<!-- Nightly Builds -->
<repository>
  <id>lingua-snapshots</id>
  <url>https://repo.karuslabs.com/repository/lingua-franca-snapshots/</url>
</repository>

<dependencies>
  <dependency>
      <groupId>com.karuslabs</groupId>
      <artifactId>lingua-franca</artifactId>
      <version>1.0.4</version>
  </dependency>
</dependencies>

<build>
    <!-- Optional but highly recommended -->
    <plugin>
        <groupId>com.karuslabs</groupId>
        <artifactId>lingua-maven-plugin</artifactId>
        <version>1.0.4</version>
        <executions>
            <execution>
                <goals>
                    <!-- Lints the usage of Lingua Franca annotations in the project -->
                    <goal>lint</goal>
                    <!-- Generates the embedded template locale file(s) at compilation -->
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</build>

1.2. Gradle

repositories {
    maven {url "https://repo.karuslabs.com/repository/lingua-franca-releases/"}
    maven {url "https://repo.karuslabs.com/repository/lingua-franca-snapshots/"}
}

compile "com.karuslabs:lingua-franca:1.0.4"

2. Registering bundle sources

ABundler contains a source registry from which bundles are loaded. Each source is bound to either a base bundle name or the global namespace.

The following examples illustrate the manual registration process and using annotations respectively. Both examples assume locale files with the base name, messages can be found in src/main/resources/translations folder.

2.1. Manual registration

import com.karuslabs.lingua.franca.Bundler;
import com.karuslabs.lingua.franca.sources.Source;
import com.karuslabs.lingua.franca.sources.ClassLoaderSource;


class Global {
    
    Source source = new ClassLoaderSource("translations");
    
    void register_to_global_namespace() {
        Bundler bundler = Bundler.bundler();
        bundler.loader().add(source);
    }
    
}

class Namespaced {
    
    Source source = new ClassLoaderSource("translations");
    
    void register_to_messages_namespace() {
        Bundler bundler = Bundler.bundler();
        bundler.loader().add("messages", source);
    }
    
}

2.2. Using Annotations

import com.karuslabs.lingua.franca.Bundler;
import com.karuslabs.lingua.franca.annotations.Namespace;
import com.karuslabs.lingua.franca.annotations.ClassLoaderSources;


@ClassLoaderSources({"translations"})
class Global {
    
    void register_to_global_namespace() {
        Bundler bundler = Bundler.bundler();
        bundler.loader().add(this);
    }
    
}

@Namespace("messages")
@ClassLoaderSources({"translations"})
class Namespaced {
    
    void register_to_messages_namespace() {
        Bundler bundler = Bundler.bundler();
        bundler.loader().add(this);
    }
    
}

3. Obtaining a bundle

The base name and locale of the bundle is necessary to obtain it from a Bundler. If the bundle for a locale is not found, the most similar bundle is returned instead.

The following examples illustrate the manual obtainment process and using annotations respectively. Both examples assume the file messages_en.yml exists while the file messages_en_GB.yml does not.

3.1. Manual obtainment

import com.karuslabs.lingua.franca.Bundle;
import com.karuslabs.lingua.franca.Bundler;

class Manual {
    
    void obtain() {
        Bundler bundler = Bundler.bundler();
        Bundle bundle = bundler.load("messages", Locale.UK); // Returns messages_en.yml
    }
    
}

3.2. Using annotations

import com.karuslabs.lingua.franca.Bundle;
import com.karuslabs.lingua.franca.Bundler;
import com.karuslabs.lingua.franca.annotations.Namespace

@Namespace("messages")
class Annotated {
    
    void obtain() {
        Bundler bundler = Bundler.bundler();
        Bundle bundle = bundler.load(this, Locale.UK); // Returns messages_en.yml
    }
    
}

4. Retrieving and formatting messages

A bundle contains methods for retrieving and formatting which return either Optional<String> or nullable Strings. The following example illustrates the retrieval and formatting of messages given the contens of messages_en.yml.

Contents of messages_en.yml:

path:
    to:
        value: "value {0}"
        array: ["array {0}"]

Retrieval and formatting of messages:

import com.karuslabs.lingua.franca.Bundle;
        
String value = bundle.find("path.to.value"); // "value {0}"
String formatted = bundle.find("path.to.value", "formatted"); // "value formatted"

String value = bundle.find("path.to.array[0]"); // "array {0}"
String formatted = bundle.find("path.to.array[0]", "formatted"); // "value formatted"

Optional<String> value = bundle.get("path.to.value") // "value {0}"
Optional<String> formatted = bundle.get("path.to.value", "formatted"); // "value formatted"

Optional<String> value = bundle.get("path.to.array[0]"); // "array {0}"
Optional<String> formatted = bundle.get("path.to.array[0]", "formatted"); // "value formatted"

String[] array = bundle.messagesIfPresent("path.to.array"); // {"array{0}"}
Optional<String[]> array = bundle.messages("path.to.array"); // {"array{0}"}

5. Generating locale files

Placeholder locale files can be generated at compile-time and runtime using the @Embedded and @Platform annotations respectively. The @Embedded annotation requires a build tool plugin to detect and generate the locale files during compilation. Generation of the locale files using Maven is supported via the Lingua Maven Plugin using the lingua-maven-plugin:generate goal.

The following examples illustrate the generation of locale files at runtime and compile-time respectively. Both examples assume the file messages.yml exists in the src/main/resources/translations folder.

5.1. Runtime generation

The following example generates messages_en_GB.yml in the folder in which the JAR is located.

import com.karuslabs.lingua.franca.template.Templates;
import com.karuslabs.lingua.franca.template.annotations.In;
import com.karuslabs.lingua.franca.template.annotations.Platform;

@Platform(template = @In(embedded = "translations/message.yml"), locales = {"en_GB"}, destination = "./")
class Runtime {
    
    void generate() {
        Templates.fromPlatforms(this);
    }
    
}

5.2. Compile-time generation

The following example generates messages_en_GB.yml in src/main/resources/translations. It requires a build tool plugin, i.e. Lingua-Maven-Plugin to generate the file.

import com.karuslabs.lingua.franca.template.Templates;
import com.karuslabs.lingua.franca.template.annotations.Embedded;

@Embedded(template = "translations/messages.yml", locales = {"en_GB"}, destination = "translations")
class CompileTime {
    
}

6. Further Information

For more information, please refer to the Javadoc and example project.

Clone this wiki locally