Module gettext

A pure Lua implementation of a gettext subset.

Example:

local _ = require("gettext")           -- gettext()
local C_ = _.pgettext                  -- pgettext()
local N_ = _.ngettext                  -- ngettext()
local NC_ = _.npgettext                -- npgettext()
local T = require("ffi/util").template -- ffi.util.template()

-- The most common use case with regular gettext().
local simple_string = _("item")

-- A more complex example. The correct plural form will be automatically
-- selected by ngettext() based on the number.
local numbered_string = T(N_("1 item", "%1 items", num_items), num_items)

It's required to pass along the number twice, because ngettext() doesn't do anything with placeholders. See ffi.util.template() for more information about the template function.

Functions

gettext (msgid) Returns a translation.
ngettext (msgid, msgid_plural, n) Returns a plural form.
npgettext (msgctxt, msgid, msgid_plural, n) Returns a context-disambiguated plural form.
pgettext (msgctxt, msgid) Returns a context-disambiguated translation.


Functions

gettext (msgid)
Returns a translation.

Parameters:

Returns:

    string translation

Usage:

    local _ = require("gettext")
    local translation = _("A meaningful message.")
ngettext (msgid, msgid_plural, n)
Returns a plural form.

Many languages have more forms than just singular and plural. This function abstracts the complexity away. The translation can contain as many pluralizations as it requires.

See gettext plural forms and translating plural forms for more information.

It's required to pass along the number twice, because ngettext() doesn't do anything with placeholders. See ffi.util.template() for more information about the template function.

Parameters:

Returns:

    string translation

Usage:

    local _ = require("gettext")
    local N_ = _.ngettext
    local T = require("ffi/util").template
    
    local items_string = T(N_("1 item", "%1 items", num_items), num_items)
npgettext (msgctxt, msgid, msgid_plural, n)
Returns a context-disambiguated plural form.

This is the logical combination between ngettext() and pgettext(). Please refer there for more information.

Parameters:

Returns:

    string translation

Usage:

    local _ = require("gettext")
    local NC_ = _.npgettext
    local T = require("ffi/util").template
    
    local statistics_items_string = T(NC_("Statistics", "1 item", "%1 items", num_items), num_items)
    local books_items_string = T(NC_("Books", "1 item", "%1 items", num_items), num_items)
pgettext (msgctxt, msgid)
Returns a context-disambiguated translation.

The same string might occur multiple times, but require a different translation based on context. An example within KOReader is Pages meaning page styles (within the context of style tweaks) and Pages meaning number of pages.

We generally don't apply context unless a conflict is known. This is only likely to occur with short strings, of which of course there are many.

See gettext contexts for more information.

Parameters:

Returns:

    string translation

Usage:

    local _ = require("gettext")
    local C_ = _.pgettext
    
    local copy_file = C_("File", "Copy")
    local copy_text = C_("Text", "Copy")
generated by LDoc 1.5.0 Last updated 2024-03-18 16:45:36