Struct gettextrs::TextDomain

pub struct TextDomain { /* fields omitted */ }

A text domain initializer builder which finds the path to bind by searching translations in the system data paths and optionally in user specified paths.

TextDomain takes care of calling the setlocale, bindtextdomain, bind_textdomain_codeset and textdomain.

Defaults

• 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.
• bind_textdomain_codeset is not invoked by default. Use codeset to specify a codeset.
• 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 defined, current path 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 name.mo is used for the call to bindtextdomain.

Examples

Basic usage:

use gettextrs::TextDomain;

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

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()
           .unwrap();

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(TextDomainError::TranslationNotFound(lang)) => {
        format!("translation not found for {}", lang)
    }
    Err(TextDomainError::InvalidLocale(locale)) => {
        format!("invalid locale {}", locale)
    }
};
println!("Textdomain init result: {}", init_msg);

Methods

impl TextDomain

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

Creates a new builder instance of TextDomain with the specified name.

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 to not call bind_textdomain_codeset.

Examples

use gettextrs::TextDomain;

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

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 translation 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<String>, TextDomainError>

Search for translations in the search paths and initialize the locale and textdomain. Return an Option with the locale (i.e. the result from the call to setlocale) if:

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

Examples

use gettextrs::TextDomain;

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

Trait Implementations

impl Default for TextDomain

fn default() -> TextDomain

Returns the "default value" for a type.

impl Debug for TextDomain

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

Formats the value using the given formatter.