DOCSEARCHbyAlgolia
Submit Docs

i18n.lua

repository·master·Indexed 43 days ago

https://github.com/kikito/i18n.lua

A Lua internationalization library providing translation loading, locale management, and variable interpolation. It supports Unicode CLDR plural rules, locale ancestry fallback mechanisms, and multiple interpolation styles including standard %{name} and traditional Lua formatting.

Tokens
1.5K
Snippets
4
Records
6
Agent score
5%

What's inside i18n.lua

  1. How fallback mechanisms work

    master

    When a translation key is not found, i18n.lua follows this search order:

    1. Locale Ancestry: It looks in the current locale's parents. Parents are determined by splitting the locale string by hyphens (-). For example, if the locale is en-US, it will check en if the key is missing in en-US.
    2. Fallback Locale: If not found in the ancestry, it searches the 'fallback locale' (which defaults to en). If the fallback locale has parents, those are searched as well.
    3. Default Key: If all locales fail, it looks for a special default key within the provided translation data.
    4. Nil: If none of the above succeed, the function returns nil.

  2. How pluralization works in i18n.lua

    master

    The library implements Unicode CLDR plural rules. When you call a translation key that contains a table of plural forms (e.g., one, few, many, other), the library automatically selects the correct form based on the current locale and the numeric value provided in the parameters.

    Custom Pluralization

    If you are using a custom or invented language, you can provide a custom pluralization function as the second argument to i18n.setLocale(locale, plural_function). This function must accept a number and return a string representing the rule (e.g., 'one', 'few', 'other').

    Locale Rooting

    The library determines the rule by finding the 'root' of the locale. For example, if the locale is fr-CA, it will apply fr rules.

    i18n.load({
  en = {
    msg = {
      one   = "one message",
      other = "%{count} messages"
    }
  },
  ru = {
    msg = {
      one   = "1 сообщение",
      few   = "%{count} сообщения",
      many  = "%{count} сообщений",
      other = "%{count} сообщения"
    }
  }
})

-- English usage
i18n.setLocale('en')
i18n('msg', {count = 1}) -- one message

-- Russian usage
i18n.setLocale('ru')
i18n('msg', {count = 5}) -- 5 сообщений

  3. Structure of language files for i18n.lua

    master

    You can store translations in individual files or a single consolidated file. Each file must return a Lua table where the top-level keys are the locale identifiers.

    Individual Language Files

    Each file (e.g., de.lua) should return a table containing the specific locale key:

    return {
  de = {
    good_bye = "Auf Wiedersehen!",
    -- ...
  }
}

    Consolidated Translation File

    You can also store all languages in one file:

    return {
  de = {
    good_bye = "Auf Wiedersehen!"
  },
  fr = {
    good_bye = "Au revoir !"
  }
}

    Use i18n.loadFile('path/to/file.lua') to load these files into the library.

    -- Example of an individual file: de.lua
return {
  de = {
    good_bye = "Auf Wiedersehen!",
    age_msg = "Ihr Alter beträgt %{age}.",
    phone_msg = {
      one = "Sie haben eine neue Nachricht.",
      other = "Sie haben %{count} neue Nachrichten."
    }
  }
}

  5. Get started with i18n.lua

    master

    To use i18n.lua, require the module and use i18n.load to provide translation data or i18n.loadFile to load external files. You must set the translation context using i18n.setLocale before retrieving translations. Translations can be retrieved using either i18n.translate(key) or the shorthand i18n(key, [params]).

    Basic Workflow

    1. Load data: Use i18n.load({...}) or i18n.loadFile('path/to/file.lua').
    2. Set locale: Use i18n.setLocale('en').
    3. Translate: Use i18n('key', {params}).
    i18n = require 'i18n'

-- Loading translations
i18n.load({
  en = {
    good_bye = "good-bye!",
    age_msg = "your age is %{age}."
  }
})

-- Setting context
i18n.setLocale('en')

-- Getting translations
print(i18n('good_bye')) -- good-bye!
print(i18n('age_msg', {age = 18})) -- your age is 18.

  6. Interpolate variables in translations

    master

    i18n.lua supports three different interpolation styles:

    1. Standard (%{name}): The most common way. Uses %{key} syntax.
    2. Traditional Lua (%s, %d): Uses standard Lua string formatting. Requires passing a table of values as the second argument.
    3. Combined (%<name>.q): A hybrid approach allowing type suffixes:
      • %<name>.q: String (quoted)
      • %<name>.d: Decimal/Number
      • %<name>.o: Other (e.g., for complex formatting)
    -- Standard interpolation
i18n.set('variables', 'Interpolating variables: %{name} %{age}')
i18n('variables', {name='john', age=10})

-- Traditional Lua way
i18n.set('lua', 'Traditional Lua way: %d %s')
i18n('lua', {1, 'message'})

-- Combined way
i18n.set('combined', 'Combined: %<name>.q %<age>.d %<age>.o')
i18n('combined', {name='john', age=10})