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.

Macros

dcgettext	Like dcgettext, but allows for formatting.
dcngettext	Like dcngettext, but allows for formatting.
dgettext	Like dgettext, but allows for formatting.
dngettext	Like dngettext, but allows for formatting.
gettext	Like gettext, but allows for formatting.
ngettext	Like ngettext, but allows for formatting.
npgettext	Like npgettext, but allows for formatting.
pgettext	Like pgettext, but allows for formatting.

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.