WordWeaver Usage Guide

Usage

Initializing

Before you can use the WordWeaver instance it has to be initialized.

Simple


import io.github.milkdrinkers.wordweaver.Translation;
import io.github.milkdrinkers.wordweaver.config.TranslationConfig;
 
// Create your WordWeaver config
TranslationConfig config = TranslationConfig.builder()
    .namespace("wordweaver:example") // The namespace of your plugin/mod (required)
    .translationDirectory(Paths.get("languages")) // The directory bundle files will be extracted to
    .defaultLocale("en_US") // The fallback locale
    .locale("fr_FR") // The active locale
    .build();
 
// Initialize WordWeaver
Translation.initialize(config);

Advanced


import io.github.milkdrinkers.wordweaver.Translation;
import io.github.milkdrinkers.wordweaver.config.TranslationConfig;
 
// Create your WordWeaver config
TranslationConfig config = TranslationConfig.builder()
    .namespace("wordweaver:example") // The namespace of your plugin/mod (required)
    .translationDirectory(Paths.get("languages")) // The directory bundle files will be extracted to
    .defaultLocale("en_US") // The fallback locale
    .locale("fr_FR") // The active locale
    .resourcesDirectory(Paths.get("lang")) // Where original bundle files are located inside your programs resource directory
    .extractBundles(true) // Extract missing bundle files
    .updateBundles(true) // Update existing bundle files in translationDirectory with missing keys
    .componentConverter(text -> Component.text(text)) // Any Function<String, Component> that converts strings to components
    .build();
 
// Initialize WordWeaver
Translation.initialize(config);

Using Translations


// Get a string from the active locale
String message = Translation.of("messages.welcome");
 
// Get a string with a fallback if the key doesn't exist in either the selected locale or fallback/default locale
String greeting = Translation.of("messages.greeting", "Hello, World!");
 
// Get a list of strings
List<String> rules = Translation.ofList("server.rules");
 
// Get translations as Adventure Components
Component welcomeMessage = Translation.as("messages.welcome");
Component errorMessage = Translation.as("messages.error", Component.text("An error occurred"));
List<Component> helpMessages = Translation.asList("help.commands");

Translatable Components

WordWeaver registers with Adventure’s GlobalTranslator, so your translations are also available as translatable components, rendered in each viewer’s own locale. This allows your translations to have indexed (<arg:0>) and named (<name>) arguments.

Given this en_US.json:

en_US.json


{
  "messages": {
    "welcome": "<gradient:green:aqua>Welcome, <arg:0>!</gradient>",
    "joined": "<gray><player> joined the game</gray>"
  }
}


import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.minimessage.MiniMessage;
import net.kyori.adventure.text.minimessage.translation.Argument;
 
// Indexed arguments resolve <arg:0>, <arg:1>, ...
audience.sendMessage(Component.translatable("messages.welcome", Component.text(name)));
 
// Named argument -> <player> (net.kyori.adventure.text.minimessage.translation.Argument)
audience.sendMessage(Component.translatable("messages.joined", Argument.component("player", Component.text(name))));
 
// Or directly from any MiniMessage string via the <lang> tag
audience.sendMessage(MiniMessage.miniMessage().deserialize("<gray>[Server]</gray> <lang:messages.welcome:'" + name + "'>"));

The component is rendered automatically in the player’s locale, falling back to the default locale if necessary.

Indexed and whole array keys work here too: Component.translatable("server.rules.1") resolves the first element in a list, and Component.translatable("server.rules") resolves the whole array.

ⓘ

The translatable path always parses values as MiniMessage, independent of your componentConverter. Supply a custom MiniMessage instance (e.g. with extra tag resolvers) via .miniMessage(...) on the config builder.

Changing Settings

After changing settings, a reload is required to apply the changes.


// Change the active locale
Translation.setLocale("fr_FR");
 
// Change the default/fallback locale
Translation.setDefaultLocale("en_US");
 
// Reload to apply new locale settings
Translation.reload();
 
// Get the active locale
String current = Translation.getLocaleTag();
 
// Get the default locale
String defaultLocale = Translation.getDefaultLocaleTag();

Reloading Translation Files


// Reloads all translations from disk
Translation.reload();

Information

File Formats

WordWeaver picks a parser by file extension. The core artifact includes a .properties parser out of the box. .json/.jsonc support is provided by the optional wordweaver-json or wordweaver-json-shaded modules (see installation), adding either to the classpath registers it automatically. You can also register your own format by implementing TranslationParser and passing it to .parser(...) on the config builder.

Each supported locale has its own file named after the locale code (e.g. en_US.properties, fr_FR.json, de_DE.jsonc, sv_SE.json). Files are extracted to, and loaded from, the translationDirectory.

.properties files cannot express lists, so ofList/asList return single-element lists for them. Use a JSON module if you need lists. Cross references (<key:other.key>) work in every format.

Example en_US.properties:


messages.welcome=Welcome to our server!
messages.goodbye=Goodbye, see you soon!
messages.error=An error occurred: {0}

Example en_US.json (requires a JSON parser module):


{
  "messages": {
    "welcome": "Welcome to our server!",
    "goodbye": "Goodbye, see you soon <player_name>!",
    "error": "An error occurred: {0}"
  },
  "server": {
    "rules": [
      "Be respectful to other players",
      "No griefing or stealing",
      "Have fun!"
    ]
  }
}

Extracting Files

When enabled, original translation files shipped with your program will be extracted to the translationDirectory on initialization.

By default, the library looks for original translation files inside your /resources/lang/ directory.


TranslationConfig config = TranslationConfig.builder()
    .namespace("wordweaver:example") // The namespace of your plugin/mod (required)
    .translationDirectory(Paths.get("languages")) // The directory bundle files will be extracted to
    .resourcesDirectory(Paths.get("lang")) // Where original bundle files are located inside your programs resource directory
    .extractBundles(true) // Defaults to true
    .build();

Adding Missing Keys To Outdated Translation Files

When enabled, on initialization, WordWeaver will try to add missing keys from original translation files to their extracted counterparts.

By default, the library looks for original translation files inside your /resources/lang/ directory.

The following specs will be followed:

The values of keys in the extracted file are not changed/overwritten.
Additional keys found in the extracted file are not removed, but reinserted.
For JSON files the keys are re-ordered to mirror the origin’s order. For .properties files the missing keys are appended to the end of the file.


TranslationConfig config = TranslationConfig.builder()
    .namespace("wordweaver:example") // The namespace of your plugin/mod (required)
    .translationDirectory(Paths.get("languages")) // The directory bundle files will be extracted to
    .resourcesDirectory(Paths.get("lang")) // Where original bundle files are located inside your programs resource directory
    .updateBundles(true) // Defaults to true
    .build();