How to add a new language file in i18n.lua?

Create a Lua file returning a table with locale keys and translations, then use i18n.loadFile() to load it. For example, a German file should return { de = { key = 'value' } }, as shown in the README's file structure examples.

i18n.lua vs other Lua i18n libraries like lua-i18n?

i18n.lua offers more comprehensive features like CLDR pluralization and flexible interpolation, while others might be simpler. Choose i18n.lua for projects needing standards-compliant i18n with robust fallbacks, but expect more manual setup.

Can i18n.lua load translations from a database or API?

No, i18n.lua is designed for file-based translations only. To use dynamic sources, you'd need to pre-load data into memory or extend the library manually, as it lacks built-in support for remote fetching.

How to handle custom pluralization rules in i18n.lua?

You can specify a custom pluralization function in setLocale's second parameter. This function must return keys like 'one' or 'other' based on a number, allowing support for non-standard languages, as mentioned in the pluralization section.

What's the best way to organize translation files with i18n.lua?

Use individual files per language (e.g., en.lua, de.lua) or a single consolidated file. Load them with i18n.loadFile() and ensure the table structure matches the locale keys, as detailed in the 'Using language files' section for maintainability.

How to interpolate variables with special formats in i18n.lua?

Use the combined formatting method with % .q for strings or % .d for decimals, as shown in the interpolation examples. Pass data as a table in the translate function for flexible variable handling.

i18n.lua — Lua Internationalization Library

What is i18n.lua?

i18n.lua is an internationalization library for Lua that enables developers to add multi-language support to their applications. It handles translation management, variable interpolation, and complex pluralization rules based on Unicode CLDR standards. The library simplifies locale switching and provides robust fallback mechanisms for missing translations.

Target Audience

Lua developers building applications that require localization, such as games, desktop tools, or embedded systems needing multi-language interfaces.

Value Proposition

Developers choose i18n.lua for its comprehensive feature set, adherence to internationalization standards, and lightweight design. It offers a more complete solution compared to basic Lua i18n approaches, with built-in pluralization, flexible interpolation, and easy file-based translation management.

A very complete i18n lib for Lua

Use Cases

Best For

Adding multi-language support to Lua-based games or applications
Managing translations with complex pluralization rules (e.g., Slavic languages)
Implementing locale fallback chains for missing translations
Loading translations from external files for easier maintenance
Handling variable interpolation in localized strings
Building Lua projects that require Unicode CLDR-compliant i18n

Not Ideal For

Applications requiring dynamic, database-driven translation updates without file reloading
Projects using locale formats with separators other than hyphens (e.g., underscores or spaces) for fallback ancestry
Teams seeking integrated GUI tools or automated translation management within the library
Simple Lua scripts with single-language support that don't need pluralization or complex fallbacks

Pros & Cons

Pros

CLDR Pluralization Support

Implements Unicode CLDR rules for locale-aware pluralization, as shown in the Russian example with 'one', 'few', 'many' forms, ensuring standard compliance for complex languages.

Flexible Interpolation Methods

Supports three interpolation styles: named variables (%{name}), traditional Lua formatting (%d %s), and combined formats, demonstrated in the interpolation examples for versatile string handling.

Robust Locale Fallbacks

Automatically falls back through locale ancestry (e.g., en-US to en) and a configurable default locale, as described in the fallbacks section, reducing missing translation errors.

File-Based Translation Management

Allows loading translations from individual or consolidated files via loadFile, facilitating easy organization and updates, as illustrated in the language file examples.

Cons

Hyphen-Only Locale Support

Fallback mechanism only works with hyphen-separated locales; the README explicitly states other separators like underscores or spaces are not supported, limiting compatibility with non-standard formats.

Static File Dependency

Translations must be loaded from files with no built-in support for dynamic sources like databases or APIs, making real-time updates cumbersome without manual reloading.

Manual Setup Overhead

Requires manual file creation and loading for each language, lacking automation or GUI tools, which can increase initial setup time for large projects.

Frequently Asked Questions

What is i18n.lua?

Target Audience

Lua developers building applications that require localization, such as games, desktop tools, or embedded systems needing multi-language interfaces.

Value Proposition

Use Cases

Best For

Adding multi-language support to Lua-based games or applications
Managing translations with complex pluralization rules (e.g., Slavic languages)
Implementing locale fallback chains for missing translations
Loading translations from external files for easier maintenance
Handling variable interpolation in localized strings
Building Lua projects that require Unicode CLDR-compliant i18n

Not Ideal For

Applications requiring dynamic, database-driven translation updates without file reloading
Projects using locale formats with separators other than hyphens (e.g., underscores or spaces) for fallback ancestry
Teams seeking integrated GUI tools or automated translation management within the library
Simple Lua scripts with single-language support that don't need pluralization or complex fallbacks

Pros & Cons

Pros

CLDR Pluralization Support

Implements Unicode CLDR rules for locale-aware pluralization, as shown in the Russian example with 'one', 'few', 'many' forms, ensuring standard compliance for complex languages.

Flexible Interpolation Methods

Supports three interpolation styles: named variables (%{name}), traditional Lua formatting (%d %s), and combined formats, demonstrated in the interpolation examples for versatile string handling.

Robust Locale Fallbacks

Automatically falls back through locale ancestry (e.g., en-US to en) and a configurable default locale, as described in the fallbacks section, reducing missing translation errors.

File-Based Translation Management

Allows loading translations from individual or consolidated files via loadFile, facilitating easy organization and updates, as illustrated in the language file examples.

Cons

Hyphen-Only Locale Support

Static File Dependency

Translations must be loaded from files with no built-in support for dynamic sources like databases or APIs, making real-time updates cumbersome without manual reloading.

Manual Setup Overhead

Requires manual file creation and loading for each language, lacking automation or GUI tools, which can increase initial setup time for large projects.

Frequently Asked Questions

i18n.lua

What is i18n.lua?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

i18n.lua

What is i18n.lua?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?