Gradle Plugin

Plugin Information

• Coordinate: dev.kordex.gradle.i18n
• Version:
• Requires Gradle:
• Minimum JDK: 17

The Kord Extensions i18n plugin is a Gradle plugin that automatically generates translations classes based on your bundles as part of your project's build process. This means that you won't need to integrate the code generators yourself.

Setting Up

Gradle Version Requirements

Because this Gradle plugin uses Gradle's problem reporting API, and the Gradle team has been dragging their heels on stabilising it, you'll need to use the same version of Gradle we build the plugin against.

This means you'll need to use Gradle with the latest plugin version.

We hope this API stabilises soon, and we can move on from this issue!

Basic

First, add the required Maven repositories to your settings.gradle.kts:

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()

        maven("https://snapshots-repo.kordex.dev")
        maven("https://releases-repo.kordex.dev")
    }
}

Next, add the plugin to your project:

Please wait, loading versions...

Convention Plugin

First, add the required Maven repositories to your buildSrc/build.gradle.kts:

repositories {
    gradlePluginPortal()
    mavenCentral()

    maven("https://snapshots-repo.kordex.dev")
    maven("https://releases-repo.kordex.dev")
}

Next, add the plugin dependency:

Please wait, loading versions...

Then, add the plugin to any convention plugins or Gradle modules that need it:

plugins {
    id("dev.kordex.gradle.i18n")
}

Finally, configure the plugin:

i18n {
    // Settings go here.
}

Configuration

You can configure the plugin using the i18n { } builder provided.

Adding Bundles

You can add translation bundles using the bundle(...) { } function, padding in the bundle name and target package, and optionally providing extra settings via the builder.

All builder settings have default values, which you can override by providing them directly. For more information on these defaults, and how you can change them globally, see the Button Defaults section.

i18n {
    bundle("template.default", "template.i18n")

    bundle("template.strings", "template.i18n") {
        className = "InternalTranslations"
    }
}

bundle(...) { ... }Receiver: Bundle

Register a translation bundle to generate code for, optionally with a configuration builder. All function arguments are required.

You can call this function multiple times if you need to generate code for more than one bundle.

Function Arguments

bundleType: String

Translation bundle, represented by its dotted package notation.

Your bundles must be placed within the basePath folder and in their own subfolder, represented by the first part of the string, whereas the last part of the string represents the prefix shared by the files in the bundle.

For example, if the basePath is the default (src/main/resources/translations/) and your bundle's base file is template/default.yaml or template/default.properties, you would provide template.default here.

classPackageType: String

Package to place the generated translation class within.

We recommend creating a dedicated .i18n subpackage for your translations.

class Bundle

Class containing the bundle's optional settings.

All of these settings have default values, which are listed in the Bundle Defaults section. You can override them for a single bundle by providing them in this builder, or you can see the Bundle Defaults section to learn how to change them globally.

basePathType: Property<File>

The base path containing your project's translation bundles.

classNameType: Property<String>

The name to give to the bundle's generated translations class.

editorConfigType: Property<File>

Path to your project's .editorconfig file, which is used to format generated code.

fileFormatType: Property<FileFormat>

A FileFormat object representing the file format used by your bundle's files.

This object is used to parse your bundle's base translation file. If you're using a format other than those provided by default with the framework, see the Extra Formats section to learn how to use them in your build script.

messageFormatType: Property<String>

String identifier representing the message format your bundle uses. This refers to the identifier property on the corresponding MessageFormat subtype.

See the messageFormat function below for a more convenient way to set this property.

outputDirectoryType: Property<File>

The directory to place the generated code within. When the plugin generates translations classes, it will also create the intermediary package directory structure, rather than directly placing the files in the output directory.

publicVisibilityType: Property<Boolean>

Whether the generated classes and properties should be marked public. Set this to false to use internal instead.

useClassClassLoaderType: Property<Boolean>

Whether the generated Bundle object should use the translation class' class-loader. Set this to false to use the system class-loader instead.

messageFormat(...)

Set the messageFormat property based on the provided argument.

Arguments

formatTypes:MessageFormatString

The message format to use. This can either be the identifier string, or the MessageFormat subtype you wish to use.

Bundle Defaults

You can set the global defaults used by all bundles via the defaults { } builder.

i18n {
    defaults {
        publicVisibility = false
    }
}

class Defaults

Class containing the global defaults used by each bundle.

basePathType: Property<File>Default: src/main/resources/translations/

The base path containing your project's translation bundles.

classNameType: Property<String>Default: Translations

The name to give to the bundle's generated translations class.

editorConfigType: Property<File>Default: /.editorconfig

Path to your project's .editorconfig file, which is used to format generated code.

The default value refers to the .editorconfig in your project's root directory, rather than the current Gradle module's directory.

fileFormatType: Property<FileFormat>Default: PropertiesFormat

A FileFormat object representing the file format used by your bundle's files.

This object is used to parse your bundle's base translation file. If you're using a format other than those provided by default with the framework, see the Extra Formats section to learn how to use them in your build script.

messageFormatType: Property<String>Default: icu-v1

String identifier representing the message format your bundle uses. This refers to the identifier property on the corresponding MessageFormat subtype.

See the messageFormat function below for a more convenient way to set this property.

outputDirectoryType: Property<File>Default: build/generated/kordex/main/kotlin/

The directory to place the generated code within. When the plugin generates translations classes, it will also create the intermediary package directory structure, rather than directly placing the files in the output directory.

publicVisibilityType: Property<Boolean>Default: true

Whether the generated classes and properties should be marked public. Set this to false to use internal instead.

useClassClassLoaderType: Property<Boolean>Default: true

Whether the generated Bundle object should use the translation class' class-loader. Set this to false to use the system class-loader instead.

messageFormat(...)

Set the messageFormat property based on the provided argument.

Arguments

formatTypes:MessageFormatString

The message format to use. This can either be the identifier string, or the MessageFormat subtype you wish to use.

Other Settings

You can further configure this plugin using these extra settings, which you can set within the i18n { } builder.

i18n {
    configureSourceSet = true
}

configureSourceSetType: Property<Boolean>Default: true

When true, the plugin will automatically add the basePath provided for all configured bundles to your project's source-sets.

Set this to false if you'd rather configure this yourself.

Extra Formats

If you need to work with file/message formats other than those the framework provides support for, you'll need to make sure they're available to use in your scripts. Third-party file formats are provided by external libraries, so you'll need to add some dependencies to get this working.

You can approach this in one of two ways.

Basic

Add the required Maven repositories and dependencies to your settings.gradle.kts:

buildscript {
    repositories {
        maven("...")
    }

    dependencies {
        classpath("group:name:version")
    }
}

Convention Plugin

Add the required Maven repositories and dependencies to your buildSrc/build.gradle.kts:

repositories {
    maven("...")
}

dependencies {
    implementation("group:name:version")
}

You should now be able to import and use any extra formats you need in your build scripts.

import com.example.MyFileFormat

// ...

i18n {
    defaults {
        fileFormat = MyFileFormat
    }
}