[![CircleCI](https://circleci.com/gh/cecton/serde-gettext.svg?style=svg)](https://circleci.com/gh/cecton/serde-gettext)
[![Latest Version](https://img.shields.io/crates/v/serde-gettext.svg)](https://crates.io/crates/serde-gettext)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT)
[![Docs.rs](https://docs.rs/serde-gettext/badge.svg)](https://docs.rs/serde-gettext)
[![LOC](https://tokei.rs/b1/github/cecton/serde-gettext)](https://github.com/cecton/serde-gettext)
[![Dependency Status](https://deps.rs/repo/github/cecton/serde-gettext/status.svg)](https://deps.rs/repo/github/cecton/serde-gettext)

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

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

 *  Example in YAML

    ```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`:

```rust
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

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

 *  Example in YAML

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

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

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

    ```yaml
    gettext: "msgid"
    ```

 *  ngettext:

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

 *  pgettext:

    ```yaml
    pgettext:
        ctx: "context"
        msgid: "msgid"
    ```

 *  dgettext:

    ```yaml
    dgettext:
        domain: "domain"
        msgid: "msgid"
    ```

 *  dngettext:

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

 *  npgettext:

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

 *  dcngettext:

    ```yaml
    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:

```yaml
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](https://docs.rs/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.