Introduction

This library is only a generic deserializer/API for gettext. With this you can use JSON or YAML (or "any" format handled by serde) to translate text through gettext and even format. It also has an API for strftime for formatting dates.

You can use it in an API service to have a translation endpoint or in a lambda to translate the input.

• Example in JSON

  {
      "ngettext": {
          "singular": "One item has been deleted",
          "plural": "%(n)s items have been deleted",
          "n": 5
      }
  }
  

• Example in YAML

  ngettext:
      singular: One item has been deleted
      plural: "%(n)s items have been deleted"
      n: 5
  

When the structure is deserialized, you can simply convert it to a translated String:

use serde_gettext::SerdeGetText;
use std::convert::TryFrom;

let yaml = r#"---
ngettext:
    singular: One item has been deleted
    plural: "%(n)s items have been deleted"
    n: 5
"#;
let s: SerdeGetText = serde_yaml::from_str(yaml).unwrap();

assert_eq!(String::try_from(s).unwrap(), "5 items have been deleted");

Formatting

• Example in JSON

  {
      "gettext": "Hello %(name)s!",
      "args": {
          "name": "Grace"
      }
  }
  

• Example in YAML

  gettext: "Hello %(name)s!"
  args:
      name: Grace
  

args can handle many different formats and use positional arguments or keyword arguments:

gettext: "%s %s %s"
args:
    - true      # "yes" (translated)
    - 3.14      # "3.14"
    -           # "n/a" (translated)

Output: "yes 3.14 n/a"

args can be added to any function:

ngettext:
    singular: "%(n)s element deleted (success: %(success)s)"
    plural: "%(n)s elements deleted (success: %(success)s)"
    n: 1
args:
    success: true

Output: "1 element deleted (success: yes)"

args can handle arrays by joining the items:

gettext: "%(value)s"
args:
    value:
        - ", "      # The separator
        - true      # "yes" (translated)
        - 3.14      # "3.14"
        -           # "n/a" (translated)

Output: "yes, 3.14, n/a"

args is recursive and can handle gettext functions:

gettext: "Last operation status: %(status)s"
args:
    status:
        ngettext:
            singular: "%(n)s element deleted (success: %(success)s)"
            plural: "%(n)s elements deleted (success: %(success)s)"
            n: 1
        args:
            success: true

Output: "Last operation status: 1 element deleted (success: yes)"

List of All Available Functions

• gettext:

  gettext: "msgid"
  

• ngettext:

  ngettext:
      singular: "msgid_singular"
      plural: "msgid_singular"
      n: 5
  

• pgettext:

  pgettext:
      ctx: "context"
      msgid: "msgid"
  

• dgettext:

  dgettext:
      domain: "domain"
      msgid: "msgid"
  

• dngettext:

  dngettext:
      domain: "domain"
      singular: "msgid_singular"
      plural: "msgid_singular"
      n: 5
  

• npgettext:

  npgettext:
      ctx: "context"
      singular: "msgid_singular"
      plural: "msgid_singular"
      n: 5
  

• dcngettext:

  dcngettext:
      domain: "domain"
      singular: "msgid_singular"
      plural: "msgid_singular"
      n: 5
      cateogy: "ctype|numeric|time|collate|monetary|messages|all|paper|name|address|telephone|measurement|identification"
  

Date and Time Formatting

You can format date and time in the locale of your choice using strftime:

strftime: "It is now: %c"
epoch: 1565854615

Output: "It is now: Thu 15 Aug 2019 09:36:55 CEST"

You will need to call set_locale and tz_set from libc-strftime to activate the locale and the timezone for your current region.

If you want to change the locale and timezone for the current process, you will need to export TZ and LC_ALL as environment variable first, then call set_locale and tz_set again.