# ainconv - Ainu language script converter
## Overview
This cargo crate provides a comprehensive set of functions for converting text between different writing systems of the [Ainu language](https://en.wikipedia.org/wiki/Ainu_language).
Currently, Latin (Romanization), Katakana and Cyrillic scripts are supported. The default Katakana output uses the broadly adopted modern forms, and optional Katakana variant flags are available for compact historical or small-kana forms.
Sentence-style input is supported by converting Ainu words while preserving surrounding non-Ainu text and punctuation. Latin input is normalized to lower case during conversion.
### Important Note
Conversion between Latin and Cyrillic script are lossless, however, conversion between Katakana and other scripts are lossy. This means that converting from Katakana to other scripts and then back to Katakana may not give the original string and the result may be ambiguous or even incorrect.
This is because the Katakana script used broadly for the Ainu language is intrinsically ambiguous. For example, it does not distinguish between *tow* and *tu* (both *トゥ*), *iw* and *i.u* (both *イウ*), *ay* and *a.i* (both *アイ*), etc. Some alternative Katakana scripts are proposed to solve this problem, but none of them are widely adopted. We are planning to support some of these alternative scripts in the future.
For a full survey of Ainu orthographic variation and how each issue maps to converter behaviour, see the shared [orthographic variation catalogue](https://github.com/mkpoli/ainconv-tests/blob/main/orthography.md) in [`ainconv-tests`](https://github.com/mkpoli/ainconv-tests) (cross-implementation; maps to its `options.schema.json`).
## Installation
Install the package using cargo
```bash
cargo add ainconv
```
or add the following line to your `Cargo.toml` file
```toml
[dependencies]
ainconv = "0.3.0"
```
## Usage
### Word Conversion
```rust
use ainconv::{
convert_kana_to_latn,
convert_latn_to_kana,
convert_cyrl_to_latn,
convert_latn_to_cyrl,
convert_kana_to_cyrl,
convert_cyrl_to_kana,
// ...
}
println!("{}", convert_kana_to_latn("イランカラㇷ゚テ")); // "irankarapte"
println!("{}", convert_latn_to_kana("irankarapte")); // "イランカラㇷ゚テ"
println!("{}", convert_cyrl_to_latn("иранкараптэ")); // "irankarapte"
println!("{}", convert_latn_to_cyrl("irankarapte")); // "иранкараптэ"
println!("{}", convert_cyrl_to_kana("иранкараптэ")); // "イランカラㇷ゚テ"
println!("{}", convert_kana_to_cyrl("イランカラㇷ゚テ")); // "иранкараптэ"
```
### Katakana Variants
`convert_latn_to_kana` keeps the default modern spelling, such as `ウィ`, `ウェ`, `ウォ`, `イ`, `ウ`, and `ン`.
Use `KanaOptions` with `convert_latn_to_kana_with_options` or `convert_cyrl_to_kana_with_options` when you need compact Katakana variants.
```rust
use ainconv::{
convert_cyrl_to_kana_with_options,
convert_latn_to_kana_with_options,
KanaOptions,
};
let opts = KanaOptions {
use_wi: true,
use_we: true,
use_wo: true,
use_small_i: true,
use_small_u: true,
use_small_n: true,
};
println!("{}", convert_latn_to_kana_with_options("wiki", &opts)); // "ヰキ"
println!("{}", convert_latn_to_kana_with_options("wenkur", &opts)); // "ヱンㇰㇽ"
println!("{}", convert_cyrl_to_kana_with_options("айну", &opts)); // "アイㇴ"
```
Each `KanaOptions` field defaults to `false`, so you can opt into only the variants you need:
| `use_wi` | `ヰ` | `ウィ` |
| `use_we` | `ヱ` | `ウェ` |
| `use_wo` | `ヲ` | `ウォ` |
| `use_small_i` | `ィ` for `-y` coda | `イ` |
| `use_small_u` | `ゥ` for `-w` coda | `ウ` |
| `use_small_n` | `ㇴ` for `-n` coda | `ン` |
### Extra Functionality
#### Script Detection
Detect the script of a given string.
```rust
use ainconv::detect;
println!("{}", detect("aynu")); // "Latn"
println!("{}", detect("アイヌ")); // "Kana"
println!("{}", detect("айну")); // "Cyrl"
```
#### Syllable Splitting
```rust
use ainconv::separate;
println!("{:?}", separate("eyaykosiramsuypa")); // ["e", "yay", "ko", "si", "ram", "suy", "pa"]
```
## License
[MIT License](LICENSE) (c) 2024 mkpoli
## See also
* [ainconv - npm](https://www.npmjs.com/package/ainconv): The JavaScript version of this package
* [ainconv - PyPI](https://pypi.org/project/ainconv/): The Python version of this package
* [Module:ain-kana-conv - ウィクショナリー日本語版](https://ja.wiktionary.org/wiki/%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB:ain-kana-conv): The original Lua Scribunto module in the Japanese Wiktionary