Crate gettextrs

Safe Rust bindings for gettext.

Usage:

use gettextrs::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Specify the name of the .mo file to use.
    textdomain("hellorust")?;
    // Ask gettext for UTF-8 strings. THIS CRATE CAN'T HANDLE NON-UTF-8 DATA!
    bind_textdomain_codeset("hellorust", "UTF-8")?;

    // You could also use `TextDomain` builder which calls `textdomain` and
    // other functions for you:
    //
    // TextDomain::new("hellorust").init()?;

    // `gettext()` simultaneously marks a string for translation and translates
    // it at runtime.
    println!("Translated: {}", gettext("Hello, world!"));

    // gettext supports plurals, i.e. you can have different messages depending
    // on the number of items the message mentions. This even works for
    // languages that have more than one plural form, like Russian or Czech.
    println!("Singular: {}", ngettext("One thing", "Multiple things", 1));
    println!("Plural: {}", ngettext("One thing", "Multiple things", 2));

    // gettext de-duplicates strings, i.e. the same string used multiple times
    // will have a single entry in the PO and MO files. However, the same words
    // might have different meaning depending on the context. To distinguish
    // between different contexts, gettext accepts an additional string:
    println!("With context: {}", pgettext("This is the context", "Hello, world!"));
    println!(
        "Plural with context: {}",
        npgettext("This is the context", "One thing", "Multiple things", 2));

    Ok(())
}

UTF-8 is required

By default, gettext converts results to the locale’s codeset. Rust, on the other hand, always encodes strings to UTF-8. The best way to bridge this gap is to ask gettext to convert strings to UTF-8:

bind_textdomain_codeset("hellorust", "UTF-8")?;

…or using TextDomain builder:

TextDomain::new("hellorust")
    .codeset("UTF-8") // Optional, the builder does this by default
    .init()?;

This crate doesn’t do this for you because the encoding is a global setting; changing it can affect other gettext calls in your program, like calls in C or C++ parts of your binary.

If you don’t do this, calls to gettext() and other functions might panic when they encounter something that isn’t UTF-8. They can also garble data as they interpret the other encoding as UTF-8.

Another thing you could do is change the locale, e.g. setlocale(LocaleCategory::LcAll, "fr_FR.UTF-8"), but that would also hard-code the language, defeating the purpose of gettext: if you know the language in advance, you could just write all your strings in that language and be done with that.

Modules

getters

Query gettext configuration.

Structs

TextDomain

A builder to configure gettext.

Enums

LocaleCategory

Locale category enum ported from locale.h.

TextDomainError

Errors that might come up after running the builder.

Functions

bind_textdomain_codeset

Set encoding of translated messages.

bindtextdomain

Specify the directory that contains MO files for the given domain.

dcgettext

Translate msgid to localized message from the specified domain using custom locale category.

dcngettext

Translate msgid to localized message from the specified domain using custom locale category (with plural support).

dgettext

Translate msgid to localized message from the specified domain.

dngettext

Translate msgid to localized message from the specified domain (with plural support).

gettext

Translate msgid to localized message from the default domain.

ngettext

Translate msgid to localized message from the default domain (with plural support).

npgettext

Translate msgid to localized message from the default domain (with plural support and context support).

pgettext

Translate msgid to localized message from the default domain (with context support).

setlocale

Set current locale.

textdomain

Switch to the specific text domain.