Metadata-Version: 2.4
Name: kaeris
Version: 0.1.3
Summary: AI localization CLI — translate JSON/YAML/.strings/.po/ARB/Android XML into 42 languages
Author: KAERIS
License: MIT
Project-URL: Homepage, https://kaeris.dev
Project-URL: Documentation, https://kaeris.dev/developer.html
Keywords: i18n,l10n,localization,translation,ai,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Localization
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# KAERIS i18n — CLI

AI localization from your terminal. Translate your app's strings files into **42 languages** —
locally or in CI/CD. Format-aware, placeholder-safe, and **incremental** (only new keys).

- **Zero dependencies** — pure Python stdlib, installs in a second
- **7 formats** — JSON, YAML, `.strings`, `.po`, ARB, Android XML, CSV
- **Incremental** — `--only-new` translates just the keys you added, merges the rest
- **Translation QA** — flags dropped placeholders & UI-overflow risk; `--verify` back-translates so you can check the meaning
- **CI-ready** — GitHub Action included; open a PR with fresh translations on every push

## Install

```bash
pip install kaeris
# or, without installing:
pipx run kaeris --help
```

## Quick start

```bash
# Translate a whole file into Spanish, French and Japanese
kaeris translate locales/en.json --langs es,fr,ja --out locales

# Only translate keys that are missing from the existing target files
kaeris translate locales/en.json --langs es,fr,ja --out locales --only-new

# Keep brand/product names verbatim in every language (glossary / do-not-translate)
kaeris translate locales/en.json --langs es,de --keep "KAERIS,GitHub,OpenRouter"

# Translation QA — verify meaning (back-translate) and write verify.json to review
kaeris translate locales/en.json --langs de,ja --verify

# List all supported languages
kaeris languages
```

Output files are written next to the source (or into `--out`), named by language:
`es.json`, `fr.json`, `ja.json` (or `values-es/strings.xml` for Android, etc.).

## Authentication & tiers

| Tier | How | Limit |
|------|-----|-------|
| **Free** (anonymous) | no key | 10,000 chars/file |
| **Pro / Scale** | `--key kaerisp_…` or `KAERIS_API_KEY` | 200k / 500k chars/file |
| **Lifetime (BYOK)** | `--key` **and** `--openrouter-key sk-or-…` | unlimited (you pay OpenRouter for tokens) |

```bash
export KAERIS_API_KEY=kaerisp_xxxxxxxx
export KAERIS_OPENROUTER_KEY=sk-or-v1-xxxx   # Lifetime/BYOK only
kaeris translate en.json --langs de,uk
```

Get a key at <https://kaeris.dev/pricing.html>. A free OpenRouter key: <https://openrouter.ai/keys>.

## CI/CD (GitHub Actions)

Translate new keys and open a PR automatically on every push — see
[`translate.example.yml`](../.github/workflows/translate.example.yml):

```yaml
- uses: kaeris-dev/i18n_tool/.github/actions/kaeris-translate@main
  with:
    source: locales/en.json
    languages: es,fr,de,ja
    out: locales
    only-new: "true"
```

## How incremental mode works

`--only-new` (JSON) parses your source and each existing translation, finds the keys present
in the source but missing from the target, translates **only those**, and merges them back —
preserving your existing translations and any non-string values (numbers, booleans). No more
re-translating (and re-paying for) the whole file every time you add one string.

## Environment variables

- `KAERIS_API_KEY` — API key
- `KAERIS_OPENROUTER_KEY` — OpenRouter key (BYOK)
- `KAERIS_API_URL` — override the API base URL
- `NO_COLOR` — disable coloured output

## License

MIT
