JSONLocalizeAPI

A lightweight JSON-based localization library for Necropolis mods. Provides easy multi-language support for mod-specific content.

What Is This?

JSONLocalizeAPI is a library mod (API mod) that other mods can use to add localization to their custom Necropolis content. It handles:

• Loading translations from JSON files
• Runtime language detection (follows Necropolis' language setting)
• Fallback chains (current language → English → first available)
• Per-mod translation isolation (each mod has its own translations.json)
• Translation caching for performance

Core Features

Language Support

• 8 Languages (Necropolis Default): English, Russian, French, German, Spanish, Italian, Polish, Portuguese (Brazilian.
• Runtime Detection: Automatically follows game's language setting
• Partial Translations: Missing languages gracefully fall back to English

Translation Types

1. Random Arrays: GetRandomFromArray() - Toast messages, random dialogue
2. Single Strings: GetFromObject() - UI labels etc.
3. Indexed Arrays: GetFromArrayIndex() - Sequential messages, tutorials

Performance

• Lazy Loading: Translations load only when first needed
• Assembly Caching: Each mod's JSON is parsed once and cached
• No Repeated I/O: Dictionary-based lookups (O(1) performance)

You can safely call API methods frequently without performance concerns.

Security

• Graceful Fallbacks: Never crashes - always returns valid string
• Per-Mod Isolation: Each mod has its own translations (no conflicts)
• Debug Mode: Detailed logging for troubleshooting

Developer Friendly

• Simple API: 3 methods cover all use cases
• No Setup Required: Just call the API
• BepInEx 5.x: Standard modding framework

Installation

For Players

You need to install this so the mods relying on this API can properly display translations.

For Mod Developers

Head over to the mod's GitHub page for detailed documentation.

FAQ

Q: Can I use this to retranslate the game's content?

• A: Not really. This is only efficient for new content added by your mod - things like button/setting names, dialogue pieces, item descriptions if it's one or two objects. For large scale translations and big amounts of text it's best to use CSVPatcher.

Q: Do I need to bundle JSONLocalizeAPI.dll with my mod?

• A: No. Just add it as a dependency in manifest.json. Players will download it automatically.

Q: Can multiple mods share one translations.json?

• A: No. Each mod should have its own. The API keeps them isolated by assembly.

Q: What if my translations.json is missing?

• A: The API gracefully falls back to your hardcoded strings. Your mod won't crash.

Q: Can I add custom languages not in the game?

• A: Yes, if another mod adds support for it. The API reads from Necro.UI.Strings.CurrentLang.

Q: Does this work with CSVPatcher mods?

• A: Yes, they're complementary.

Changelog

1.0.0

• Initial Thunderstore release

Credits

• Author: KoMiKoZa
  Discord: komikoza
• SimpleJSON: Bunny83 (MIT License)

Support

• Website: Mod Documentation
• Source Code: GitHub
• Issues: Report bugs on Discord or GitHub Issues