Getting started with I18N Manager

This guide explains two ways to start using I18N Manager: generating a new application with I18N Manager already integrated, or integrating it by hand into an existing application.

Quick Start with Craft

The fastest way to try I18N Manager is to generate a new application with Craft, the AppJars project generator. Craft produces a runnable Spring Boot and Vaadin project with I18N Manager already integrated, so none of the manual integration steps are needed.

1. Open craft.appjars.com and select the I18N Manager card in the Modules section. Other AppJars can be selected as well; Craft wires them together.
2. Adjust the Project and Appearance settings if needed, and click Download project.
3. Extract the downloaded archive and run docker compose up -d from the extracted folder. The first start takes a few minutes while the application image is built. To run the application with Maven instead, run mvn spring-boot:run.
4. Open http://localhost:8080; the I18N Manager views are in the navigation drawer.

Unless User Manager or Issue Tracker is selected as well, the generated application has no login page and every view is accessible without signing in.

The Craft Project Generator page describes every option and the contents of the generated project. Continue with Testing the Application to try I18N Manager.

Manual Integration

Prepare the Application

The following steps integrate I18N Manager into an existing Spring Boot and Vaadin application. To follow them from a blank application, open Craft, leave every module unselected, and click Download project. Extract the archive, import it into your IDE of choice, and verify the application starts correctly by running the main class. A project generated by Craft already declares the AppJars repository, so the next step can be skipped.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-i18n-manager-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-i18n-manager-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-i18n-manager-business-impl</artifactId>
</dependency>

After adding them, build the application to confirm that the dependencies are resolved correctly.

Configure the Application Class

I18N Manager registers its components and entities through Spring Boot auto-configuration, but it does not enable its Spring Data repositories. Add @EnableJpaRepositories to the application class so that they are found:

@SpringBootApplication
@EnableJpaRepositories(basePackageClasses = I18nManagerAutoConfiguration.class)
public class Application implements AppShellConfigurator {
    // ...
}

The imports are:

• org.springframework.data.jpa.repository.config.EnableJpaRepositories
• com.appjars.i18nmanager.I18nManagerAutoConfiguration

Note

If the application already declares @EnableJpaRepositories for its own repositories, add the I18N Manager package to the existing annotation rather than declaring a second one.

Configure the Router Layout

Inject the RouteConfigurer provided by I18N Manager and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("I18nManagerRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.i18nmanager.flow.util.RouteConfigurer.

Add the Views to the Navigation

Add the I18N Manager views to the application's navigation menu. Insert the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

if (accessChecker.hasAccess(LanguageCrudView.class)) {
    nav.addItem(new SideNavItem("Languages", LanguageCrudView.class, LineAwesomeIcon.LANGUAGE_SOLID.create()));
}
if (accessChecker.hasAccess(TranslationItemCrudView.class)) {
    nav.addItem(new SideNavItem("Translations", TranslationItemCrudView.class, LineAwesomeIcon.GLOBE_SOLID.create()));
}

The imports for the view classes are:

• com.appjars.i18nmanager.flow.view.LanguageCrudView
• com.appjars.i18nmanager.flow.view.TranslationItemCrudView

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true

I18N Manager registers its database-backed I18NProvider as a @Primary bean, so Vaadin picks it up automatically. Do not set vaadin.i18n.provider. Vaadin resolves the provider from the Spring context, and reads that property only when no single I18NProvider bean exists.

Note

The bundled messages_<locale>.properties files are decoded as UTF-8 when scanning for missing keys. If your resource bundles use a different charset, set com.appjars.i18nmanager.properties.encoding (for example, com.appjars.i18nmanager.properties.encoding=ISO-8859-1).

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.example.demo,com.flowingcode,com.appjars

Testing the Application

Start the application by running the main Spring Boot class. After it starts, log in and navigate to Languages in the menu.

Create a new language by clicking the New Language button and filling in the language key (e.g. en) and region (e.g. US). Once the language is saved, navigate to Translations to manage the translation keys and their values for each language.