AtlasLang

AtlasLang is a production-grade multilingual engine designed for centralized language management across plugins and server components.

It provides strict validation, structured file handling, database-backed player language storage and full PlaceholderAPI integration.

GitHub Repository:
https://github.com/nauticstudios/atlaslang

Public API:
https://github.com/nauticstudios/AtlasLang/blob/master/src/main/java/com/github/nautic/api/AtlasAPI.java

---

Overview

AtlasLang provides:

• Per-player language storage
• Locale → folder mapping system
• Strict language validation
• Recursive YAML file loading
• PlaceholderAPI expansion
• Public developer API
• GitHub synchronization
• Database persistence
• Runtime dependency loading

Note

AtlasLang enforces strict validation to prevent invalid or unregistered languages from being used.

---

Architecture

Main Plugin (AtlasLang)

Responsible for:

• Runtime dependency loading
• Configuration initialization
• Language registration
• Command system
• Placeholder expansion registration
• GitHub sync management
• Database initialization

---

LanguageManager

Handles:

• Language registration
• Locale → folder mapping
• Default language fallback
• Strict resolution
• Reload logic

Configuration format:

default: english

register:
  languages:
    - en:english:messages.yml
    - es:spanish:messages.yml

Format:

locale:folder:defaultFile

---

FileManager

Responsible for:

• Recursive language folder loading
• YAML caching
• Dynamic file resolution
• Default file generation
• Cache clearing

Language directory:

/plugins/AtlasLang/languages/

Example:

languages/
 ├── english/
 │   ├── messages.yml
 │   ├── scoreboard.yml
 │   └── system.yml
 └── spanish/
     ├── messages.yml
     ├── scoreboard.yml
     └── system.yml

---

LangHandler

Handles:

• Message retrieval
• String and list resolution
• Placeholder injection
• Fallback handling
• Missing path safety

If a path is invalid, a safe fallback message is returned.

Malformed or missing language files will never crash the server.

---

PlaceholderAPI Integration

Identifier:

%alang_...%

Format:

%alang_(file)_(path)%

Examples:

%alang_(messages)_(join_message)%
%alang_(lobby:scoreboard)_(title)%

Behavior:

• Resolves player language from database
• Falls back to default if invalid
• Validates file existence
• Validates path existence

Tip

Placeholders must follow the format (file)_(path) or they will return an invalid format message.

---

Public Developer API

Static API access:

AtlasAPI.get(player, "path.to.message");
AtlasAPI.get(uuid, "path.to.message");
AtlasAPI.get("english", "path.to.message");

With fallback:

AtlasAPI.getOrDefault(player, "path.to.message", "Fallback");

Validation:

AtlasAPI.has("english", "path.to.message");
AtlasAPI.isLanguageRegistered("english");

Player language:

AtlasAPI.setLanguage(player, "english");
AtlasAPI.getLanguage(player);

Managers:

AtlasAPI.getLanguageManager();
AtlasAPI.getLangHandler();

Addon access:

AtlasAPI.getAddon(player, "path.to.message");

---

Commands

Base command:

/atlaslang

Command	Permission
/atlaslang help	—
/atlaslang list	atlaslang.list
/atlaslang aliases	atlaslang.aliases
/atlaslang set <player> <language>	atlaslang.set
/atlaslang reset <player>	atlaslang.reset
/atlaslang info <player>	atlaslang.info
/atlaslang reload	atlaslang.reload
/atlaslang github sync	atlaslang.github
/atlaslang github status	atlaslang.github

Full access:

atlaslang.admin

---

GitHub Synchronization

Supports automatic language sync from a repository.

Example:

github:
  repository:
    name: "owner/repository"
    branch: "main"

  authentication:
    type: "none"
    token: ""

  paths:
    remote-root: "languages"
    local-root: "languages"

  sync:
    create-missing: true
    overwrite-existing: true
    delete-missing: false
    reload-after-sync: true

• Runs asynchronously
• Does not block the main thread
• Supports optional token authentication

---

Database Integration

Player language storage process:

1. Retrieve stored language
2. Validate registration
3. Fallback to default if invalid

Database safely closes on plugin disable.

---

Runtime Dependency Loading

Dependencies are loaded during onLoad() from:

• Maven Central
• CodeMC Repository

Libraries are relocated and isolated to prevent conflicts.

---

Language Resolution Flow

1. Player language requested
2. LanguageManager resolves locale
3. Folder validated
4. FileManager loads file
5. Path resolved
6. Fallback applied if necessary

Strict validation prevents invalid states.

---

Designed For

• Multi-language networks
• Centralized language control
• Scoreboards
• GUIs and menus
• Placeholder-based systems
• Modular plugin ecosystems

---

Stability Guarantees

• No fatal errors for missing translations
• Strict language validation
• Safe fallback system
• Async GitHub sync
• Runtime-safe reload