kielet - v4.0.0

kielet

Types

Context

</>

Translation context, containing both the database and the active language in one type for convenience.

Note that this is not the same as the context given to the functions pgettext and npgettext.

pub type Context {
  Context(database: Database, language: String)
}

Constructors 

  • Context(database: Database, language: String)

Database

opaque </>

The database stores all of the loaded languages.

pub opaque type Database

Language

opaque </>

A single language loaded from a file.

pub opaque type Language

LanguageLoadError

</>

Error returned when an MO file is loaded.

pub type LanguageLoadError {
  MoParseError(err: @internal ParseError)
  PluralFormsLoadError(err: @internal LoadError)
}

Constructors 

  • MoParseError(err: @internal ParseError)

    The MO file could not be parsed.

  • PluralFormsLoadError(err: @internal LoadError)

    The plural forms in the MO file were invalid or missing.

Values

add_language

</> 
pub fn add_language(db: Database, lang: Language) -> Database

Add a language to the database.

get_language_code

</> 
pub fn get_language_code(lang: Language) -> String

Get the language’s language code.

gettext

</> 
pub fn gettext(context: Context, msgid: String) -> String

Translate the given singular message.

If there is a failure to translate the message, the given message is returned as-is. Causes for such a failure are:

  • if no translations have been loaded for the language,
  • if there is no translation for this message for the language, or
  • if the translation for this message is plural.

Example:

// Imported with kielet.{gettext as g_}
io.println(
  g_(ctx, "Sleep tight in a new light through another warning call")
)

load_language

</> 
pub fn load_language(
  code: String,
  mo_file: BitArray,
) -> Result(Language, LanguageLoadError)

Load a language from the given MO file.

new_database

</> 
pub fn new_database() -> Database

Create a new empty database.

ngettext

</> 
pub fn ngettext(
  context: Context,
  singular: String,
  plural: String,
  n: Int,
) -> String

Translate the given plural message. n is the amount of countable items in the message. For example for the English language, from "%s bunny" and "%s bunnies", the latter would be returned when n is anything except 1.

Note that this function does no replacing of any placeholder. It is only convention to use %s in place of the amount in the message, and it will not be altered by this function. Replacing of the amount is left to the user.

If there is a failure to translate the message, the given message is returned, in singular or plural, using the English pluralisation rules. Causes for such a failure are:

  • if no translations have been loaded for the language,
  • if there is no translation for this message for the language,
  • if the translation for this message is singular,
  • if the plural form algorithm returned a form that does not exist in the translation, or
  • if the translation file did not have a Plural-Forms header.

Example:

// Imported with kielet.{ngettext as n_}

let n = 100

io.println(
  string.replace(
    n_(
      ctx,
      "That's better than a rabbit",
      "That's better than %s rabbits",
      n
    ),
    "%s",
    int.to_string(n)
  )
)

npgettext

</> 
pub fn npgettext(
  context: Context,
  msgctxt: String,
  singular: String,
  plural: String,
  n: Int,
) -> String

Translate plural message with given context.

See the documentation of pgettext and ngettext for other details.

// Imported with kielet.{npgettext as np_}
np_(ctx, "A physical sign with text on it", "A sign", "%s signs", 5)
np_(ctx, "A word in a sign language", "A sign", "%s signs", 5)

pgettext

</> 
pub fn pgettext(
  context: Context,
  msgctxt: String,
  msgid: String,
) -> String

Translate singular message with given context. If the context does not match any for the translation, even if the message matches, the translation will fail and the original message from the source will be returned.

Note that having a context of an empty string and not having a context are not the same thing! I.e., any translation used with pgettext cannot be loaded using gettext and vice versa. In such a case they must be translated twice.

See the documentation of gettext for other details.

Example:

// Imported with kielet.{pgettext as p_}
p_(ctx, "Lead (the element)", "Lead")
p_(ctx, "To lead (verb)", "Lead")
✨ Search Document