# traduki
An asset translation toolkit for Rust, which compiles asset files into
the binary, but choses the appropriate translation at runtime via the
`LANG` environment locale.
Probably only works on Linux/MacOS at the moment.
```rust
include!(concat!(env!("OUT_DIR"), "/traduki.rs"));
fn main() {
use traduki::app;
println!("{}: {}", app::name(), app::description());
}
```
## Project state
This project is very new and developed with
[qaul.net](https://git.open-communication.net/qaul/qaul.net) as a
testing ground, as part of the Rust CLI-WG. If you have feedback,
feel free to send it to our [mailing
list](mailto:cli-wg@rust-lang.org)!
The above example accesses translation data manually, but in the
future it would be great if libraries (such as cli parsers, web
servers, etc) could also access this data to make certain integrations
easier. All of this is still very work in progress.
## The problem
We've all built applications that handle user-facing text. Whether
they are error messages, help messages, the general UI text, ...
almost all application text can and should be translated into the
user's preferred language to make using software as accessible as
possible.
However, managing translations is hard, especially when it cames to
accessing strings in different parts of an application, or even in
multiple crates in the same workspace.
Additionally applications aren't the only things that can be
translated: manual pages, help texts, even static websites can all be
translated and generated with language specific texts.
## Overview
`traduki` adds a "language assets" directory, in which users can create
a losely managed structure of texts and asset files for translations.
### Asset directory structure
A popular approach to handling translation assets is to have a
top-level language section, followed by a custom tree of objects. The
problem of this approach is that it makes it incredibly easy for
different language trees to drift out of sync with each other.
Instead, `traduki` uses the "wikipedia model": at the top level is a
set of categories, filled with sub-categories and "pages" (assets).
Each asset is a folder which contains language specific files.
This way it's much easier to compare the state of translations for
each language at a glance and discourages pages or sections to only
exist in one language.
### Format
Following is a very simple directory layout of how to use `taduki`.
For more complex examples, check the `examples` directory.
```
assets/
├── clap
│ ├── create
│ │ ├── en_GB.yml
│ │ ├── eo.yml
│ │ └── fr_FR.yml
│ └── default
│ ├── en_GB.yml
│ ├── eo.yml
│ └── fr_FR.yml
└── manual
├── en_GB.yml
├── eo.yml
└── fr_FR.yml
```
In this example the `clap` directory contains data regarding the CLI,
grouped by subcommand (with `default/` contains general arguments, the
application name, version, disclaimer, etc.)
The manual section doesn't have sub-sections and is a simple leaf node
(with three languages).
In your `build.rs` you should add this line
```rust
fn main() {
set_var("TRADUKI_DEFAULT_LANG", "en_GB");
traduki::bootstrap("assets");
}
```
In your Rust program (after initialising `taduki`, you will be able to
get assets with `crate::taduki::clap::create::my_key_here`).