WordWeaver

A modern Java translation library designed for effortless localization management in Java applications.

---

🌟 Features

• Easy Integration - Simple API with minimal setup
• Highly Configurable - Customize every aspect of the library
• Thread-Safe - Designed for concurrent environments
• Optimized - Resource efficient with a small memory footprint while providing excellent speed
• Adventure 4+ Support - Native integration for modern text components
• Java 8+ Compatibility - Supports legacy and modern java versions
• Tested - Comprehensive unit test coverage
• Multiple File Formats - .properties support out of the box, with .json/.jsonc modules, or add your own format through optional parser modules
• Advanced Features - Comes with optional advanced features like translation file extractor and updater

📦 Installation

Add WordWeaver to your project with Maven or Gradle. The core artifact ships with a .properties parser out of the box. To read .json/.jsonc files, add one of the optional JSON parser modules. Parser modules register themselves automatically once they are on the classpath.

Core

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.milkdrinkers:wordweaver:VERSION")
}

Maven

<dependency>
    <groupId>io.github.milkdrinkers</groupId>
    <artifactId>wordweaver</artifactId>
    <version>VERSION</version>
</dependency>

JSON/JSONC support (Optional)

Pick one of the following, do not add both:

• wordweaver-json - you provide the GSON dependency yourself. Best when GSON is already on your classpath (e.g. like on platforms like PaperMC).
• wordweaver-json-shaded - GSON comes bundled and relocated (shaded).

Gradle Kotlin DSL

dependencies {
    implementation("io.github.milkdrinkers:wordweaver:VERSION")

    // Option A, bring your own GSON
    implementation("io.github.milkdrinkers:wordweaver-json:VERSION")
    implementation("com.google.code.gson:gson:x.x.x")

    // Option B, uses included GSON
    implementation("io.github.milkdrinkers:wordweaver-json-shaded:VERSION")
}

Maven

<!-- Option A, bring your own GSON -->
<dependency>
    <groupId>io.github.milkdrinkers</groupId>
    <artifactId>wordweaver-json</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>x.x.x</version>
</dependency>

<!-- Option B, uses included GSON -->
<dependency>
    <groupId>io.github.milkdrinkers</groupId>
    <artifactId>wordweaver-json-shaded</artifactId>
    <version>VERSION</version>
</dependency>

Shading

Most users shade WordWeaver and its parser modules into their own jar. When you build a fat jar, you must merge service files so that every parser stays registered.

Gradle (Shadow)

tasks.shadowJar {
    relocate("io.github.milkdrinkers.wordweaver", "yourpackage.wordweaver")

    mergeServiceFiles()
}

Maven (Shade)

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <relocations>
            <relocation>
                <pattern>io.github.milkdrinkers.wordweaver</pattern>
                <shadedPattern>yourpackage.wordweaver</shadedPattern>
            </relocation>
        </relocations>
        <transformers>
            <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
        </transformers>
    </configuration>
</plugin>

Usage Example

import io.github.milkdrinkers.wordweaver.Translation;
import io.github.milkdrinkers.wordweaver.config.TranslationConfig;

// Create configuration
TranslationConfig config = TranslationConfig.builder()
    .namespace("wordweaver:example") // The namespace of your plugin/mod (required)
    .translationDirectory(Paths.get("lang")) // The directory bundle files will be stored in
    .locale("fr_FR") // The active locale
    .defaultLocale("en_US") // The fallback locale
    .build();
    
// Initialize WordWeaver
Translation.initialize(config);

// Use translations
String message = Translation.of("messages.welcome");
Component welcomeMessage = Translation.as("messages.welcome");
List<String> rules = Translation.ofList("server.rules");
List<Component> helpMessages = Translation.asList("help.commands");

Example en_US.json:

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

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.

Example en_US.json:

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

Reference keys directly:

// Indexed argument -> <arg:0>
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 + "'>"));

📚 Documentation

• Full Javadoc Documentation
• Documentation
• Maven Central

---

🔨 Building from Source

git clone https://github.com/milkdrinkers/WordWeaver.git
cd wordweaver
./gradlew publishToMavenLocal

---

🔧 Contributing

Contributions are always welcome! Please make sure to read our Contributor's Guide for standards and our Contributor License Agreement (CLA) before submitting any pull requests.

We also ask that you adhere to our Contributor Code of Conduct to ensure this community remains a place where all feel welcome to participate.

---

📝 Licensing

You can find the license the source code and all assets are under here. Additionally, contributors agree to the Contributor License Agreement (CLA) found here.

---

🔥 Consuming Projects

Here is a list of known projects using WordWeaver:

• Minecraft-Plugin-Template - Provided by default in a Minecraft Plugin Template.
• Maquillage - Maquillage a Minecraft cosmetics plugin.
• CharacterCards - CharacterCards is a Minecraft plugin allowing players to create cards describing their character.
• (Add your project here!)