Programmatic API

API Information

• Coordinate: dev.kordex.i18n:i18n-generator
• Current Version:
• Minimum JDK: 17

The i18n generator API tool allows you to generate translations classes programmatically, to suit whatever situations your code needs to handle. You can use it to generate translation classes whenever you can't use the Gradle plugin, including writing your own plugins for other build tools.

Since it gives you access to the KotlinPoet FileSpec, you can also modify the code before it is generated.

Usage

The generation API is encapsulated in a single class, TranslationsClass. Create an instance of this class, configuring it via its constructor parameters, and use writeTo() to generate the code and store the result in the given file.

Constructor Parameters

val bundleType: String

The name of the translation bundle to process. For example: template.strings.

val classNameType: StringDefault: "Translations"

Generated class name.

val classPackageType: String

Package to place the generated class in. For example: template.i18n.

val editorConfigType: Path?Default: Path(".editorconfig")

Path to your project's EditorConfig file, if it has one. The generator will use this to format the code it outputs.

val fileFormatType: FileFormatDefault: PropertiesFormat

Translations file format.

val messageFormatType: StringDefault: "icu-v1"

Message format.

val publicVisibilityType: BooleanDefault: true

Whether to generate code with the public visibility modifier. Provide false to use internal instead.

val resourceBundleType: ResourceBundle

Resource bundle object containing your bundle's base translations.

val useClassClassloaderType: BooleanDefault: false

Whether to generate bundle objects that specify the classloader used to load their containing object, rather than defaulting to the system classloader.

This is particularly useful if you're writing a plugin for something, as the i18n framework will need to load your translations from the plugin, rather than the system classloader.

Functions

writeToFile(...)

Write the generated translations object to an output directory, generating interim directories for the classPackage as necessary.

You can usually call this immediately after creating your TranslationsClass, unless you need to mess with the spec object first.

Arguments

outputDirType: File

File object representing the output directory.

Properties

These properties are provided for advanced use-cases only, and may change from version to version.

Show/Hide Internal APIs

allKeysType: List<String>

Flat list containing all of the translation keys contained within the resourceBundle property.

specType: com.squareup.kotlinpoet.FileSpec

KotlinPoet FileSpec representing the file to be generated.

This is filled as part of the TranslationClass initialisation, but you can modify it if you need to.

Example

This API is a little involved, so see below for a working example.

val bundleName = "template.strings"
val classPackage = "template.i18n"

val resourceBundle = ResourceBundle.getBundle(
    // Resource bundles don't use package specifiers for some reason.
    bundleName.replace(".", "/"),

    // Generally, you want the default translations, so we use a fake locale here.
    Locale("dummy"),

    // You could also use a URLClassLoader, for example.
    ClassLoader.getSystemClassLoader(),

    // The default, each file format object defines a control for you to use.
    PropertiesFormat.control,
)

// Create and populate a TranslationsClass object.
val translationsClass = TranslationsClass(
    bundle = bundleName,
    classPackage = classPackage,
    resourceBundle = resourceBundle,
)

// Write the generated code to file.
// You could also use `translationsClass.spec.writeTo(buffer)` if you need to work with it yourself.
translationsClass.writeTo(File("./output"))

Extra Formats

The i18n framework uses sweet-spi to load extra file/message formats from the classpath. For that reason, there's nothing special you need to do — just use any formats your IDE (and the compiler) can resolve.