Struct TextDomain

pub struct TextDomain { /* private fields */ }

A builder to configure gettext.

It searches translations in the system data paths and optionally in the user-specified paths, and binds them to the given domain. TextDomain takes care of calling setlocale, bindtextdomain, bind_textdomain_codeset, and textdomain for you.

Defaults

• bind_textdomain_codeset is called by default to set UTF-8. You can use codeset to override this, but please bear in mind that other functions in this crate require UTF-8.
• Current user’s locale is selected by default. You can override this behaviour by calling locale.
• LocaleCategory::LcMessages is used when calling setlocale. Use locale_category to override.
• System data paths are searched by default (see below for details). Use skip_system_data_paths to limit the search to user-provided paths.

Text domain path binding

A translation file for the text domain is searched in the following paths (in order):

1. Paths added using the prepend function.
2. Paths from the XDG_DATA_DIRS environment variable, except if the function skip_system_data_paths was invoked. If XDG_DATA_DIRS is not set, or is empty, the default of “/usr/local/share/:/usr/share/” is used.
3. Paths added using the push function.

For each path in the search paths, the following subdirectories are scanned: path/locale/lang*/LC_MESSAGES (where lang is the language part of the selected locale). The first path containing a file matching domainname.mo is used for the call to bindtextdomain.

Examples

Basic usage:

use gettextrs::TextDomain;

TextDomain::new("my_textdomain").init()?;

Use the translation in current language under the target directory if available, otherwise search system defined paths:

use gettextrs::TextDomain;

TextDomain::new("my_textdomain")
           .prepend("target")
           .init()?;

Scan the target directory only, force locale to fr_FR and handle errors:

use gettextrs::{TextDomain, TextDomainError};

let init_msg = match TextDomain::new("my_textdomain")
    .skip_system_data_paths()
    .push("target")
    .locale("fr_FR")
    .init()
{
    Ok(locale) => {
        format!("translation found, `setlocale` returned {:?}", locale)
    }
    Err(error) => {
        format!("an error occurred: {}", error)
    }
};
println!("Textdomain init result: {}", init_msg);

Implementations

impl TextDomain

pub fn new<S: Into<String>>(domainname: S) -> TextDomain

Creates a new instance of TextDomain for the specified domainname.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain");

pub fn locale(self, locale: &str) -> Self

Override the locale for the TextDomain. Default is to use current locale.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain")
                             .locale("fr_FR.UTF-8");

pub fn locale_category(self, locale_category: LocaleCategory) -> Self

Override the locale_category. Default is LocaleCategory::LcMessages.

Examples

use gettextrs::{LocaleCategory, TextDomain};

let text_domain = TextDomain::new("my_textdomain")
                             .locale_category(LocaleCategory::LcAll);

pub fn codeset<S: Into<String>>(self, codeset: S) -> Self

Define the codeset that will be used for calling bind_textdomain_codeset. The default is “UTF-8”.

Warning: other functions in this crate require UTF-8.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain")
                             .codeset("KOI8-R");

pub fn prepend<P: Into<PathBuf>>(self, path: P) -> Self

Prepend the given path to the search paths.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain")
                             .prepend("~/.local/share");

pub fn push<P: Into<PathBuf>>(self, path: P) -> Self

Push the given path to the end of the search paths.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain")
                             .push("test");

pub fn skip_system_data_paths(self) -> Self

Don’t search for translations in the system data paths.

Examples

use gettextrs::TextDomain;

let text_domain = TextDomain::new("my_textdomain")
                             .push("test")
                             .skip_system_data_paths();

pub fn init(self) -> Result<Option<Vec<u8>>, TextDomainError>

Search for translations in the search paths, initialize the locale, set up the text domain and ask gettext to convert messages to UTF-8.

Returns an Option with the opaque string that describes the locale set (i.e. the result of setlocale) if:

• a translation of the text domain in the requested language was found; and
• the locale is valid.

Examples

use gettextrs::TextDomain;

TextDomain::new("my_textdomain").init()?;

Trait Implementations

impl Debug for TextDomain

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.