Skip to content

README.md

Latest commit

 

History

History
229 lines (172 loc) · 8.29 KB

README.md

File metadata and controls

229 lines (172 loc) · 8.29 KB

Contributors Forks Stargazers Issues LGPL License


i18label4j

A simple and lightweight registry library with flexible identifiers and namespaces for Java.
Localize your application cleanly with typed labels, dynamic placeholders, and pluggable serializers.

Explore the docs »  ·  Report Bug  ·  Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Architecture
  5. Roadmap
  6. Contributing
  7. License
  8. Contact
  9. Acknowledgments

About The Project

i18label4j is a modular Java library for managing localizable text labels with a clean, fluent API. It provides:

  • Typed labels: distinguish between locale-aware i18n labels, global labels and immutable literal labels at compile time.
  • Placeholder substitution: register static or dynamic Placeholder objects on any label and apply them via configurable PlaceholderRule strategies (supports ${key}, {key}, %key%, <key>, and more out of the box).
  • Pluggable serializers: convert labels to any target type (plain String, Adventure Component, etc.) by registering a LabelSerializer.
  • Multiple localization sources: load translations from a flat directory DeepDirSource (supports file, resources, http and more), or implement your own LocalizationSource.
  • Format support: JSON, YAML, TOML, and Java .properties files are supported out of the box.
  • Translation caching: the CommonLabelProvider caches translations per locale with thread-safe ConcurrentHashMap internals and explicit cache eviction.
  • Fallback: it supports fallbacks to default or to a fallback string !{key} or similar

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

  • Java 21+
  • Gradle 9+ (wrapper included)

Installation

Add the repository and dependency to your build.gradle.kts:

repositories {
    maven("https://leycm.github.io/repository/")
}

dependencies {
    // API only (compile against the interface)
    compileOnly("de.leycm:label4j-api:2.0.0")

    // Full implementation (includes CommonLabelProvider, FileSource, DirSource, etc.)
    implementation("de.leycm.label4j-impl:2.0.0")
}

Or with Maven (pom.xml):

<repository>
  <id>leycm-repo</id>
  <url>https://leycm.github.io/repository/</url>
</repository>

<dependency>
  <groupId>de.leycm</groupId>
  <artifactId>label4j-api</artifactId>
  <version>2.0.0</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>de.leycm</groupId>
  <artifactId>label4j-impl</artifactId>
  <version>2.0.0</version>
</dependency>

(back to top)

Usage

For Usage and How to start explore the docs

Architecture

i18label4j
├── i18-api/          # Public API - Label, LabelProvider, Placeholder, PlaceholderRule, LabelSerializer, LocalizationSource
└── i18-impl/         # Implementation - CommonLabelProvider, LiteralLabel, LocaleLabel,
                      #                  FileSource, DirSource, FileParser, FileUtils

The library is split into two modules so downstream projects can depend only on the API and swap implementations at runtime via Instanceable.register(...).

(back to top)

Roadmap

  • Core Label API with LiteralLabel and LocaleLabel
  • CommonLabelProvider with thread-safe translation cache
  • MappingRule with 10+ built-in placeholder styles
  • FileSource and DirSource with JSON, YAML, TOML, .properties support
  • Classpath (resource://), filesystem (file://), and remote (http(s)://) URI schemes
  • Nested/hierarchical key support in DirSource
  • Hot-reload support for translation files
  • Maven / Gradle plugin for compile-time key validation
  • Additional serializer modules (Adventure, MiniMessage)

See the open issues for the full list of proposed features and known bugs.

(back to top)

Contributing

Contributions are what make open source such a great place to learn and build. Any contributions you make are greatly appreciated.

  1. Fork the project
  2. Create your feature branch (git checkout -b feat/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add some amazing Features')
  4. Push to the branch (git push origin feat/amazing-feature)
  5. Open a Pull Request

(back to top)

License

Distributed under the GNU Lesser General Public License v3.0. See LICENSE.LGPL for more information.

(back to top)

Contact

Lennard — leycm@proton.me

Project Link: https://github.com/leycm/label4j

(back to top)

Acknowledgments

(back to top)