Metadata-Version: 2.4
Name: hunayn
Version: 0.1.1
Summary: Command-line companion and quality checker for GNOME translators
Author: Ramal Rahimov
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/rehimovv/hunayn
Project-URL: Issues, https://gitlab.com/rehimovv/hunayn/-/issues
Keywords: gettext,po,translation,l10n,gnome,linter
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Localization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# Hunayn

**A command-line companion and quality checker for GNOME translators.**

Hunayn helps translation teams around the world work with
[Damned Lies](https://l10n.gnome.org) from the terminal and catches
translation mistakes before they reach a release.

> **Status:** early development. `hunayn check` is released and ready to
> use; the Damned Lies commands do not exist yet.

## Why "Hunayn"?

The project is named after **Hunayn ibn Ishaq** (809–873), the most
celebrated translator of Baghdad's House of Wisdom. He was famous not only
for the amount he translated, but for his care: before translating a text,
he collected several manuscripts, compared them and corrected their errors.
Careful checking before publishing is exactly what this tool is about.

## Checking PO files

Hunayn needs Python 3.10 or newer and has no other dependencies:

```
pip install hunayn
```

Then:

```
hunayn check az.po                     # report problems, exit 1 on errors
hunayn check po/*.po --format json     # for CI
hunayn check --ignore accelerator az.po
hunayn check --list-rules
```

Exit status: `0` no errors (warnings are allowed), `1` errors found (or
any finding with `--strict`), `2` Hunayn could not run (a file is
missing, an unknown rule was named).

Fuzzy messages are not checked unless you add `--include-fuzzy`. To
silence a rule for one message, add a translator comment:

```
# hunayn: ignore=accelerator
msgid "_Open"
msgstr "Aç"
```

The rules, how each one was measured, and what they report are described
in [docs/rules.md](https://gitlab.com/rehimovv/hunayn/-/blob/main/docs/rules.md).

## What it is for

### 1. Talk to Damned Lies for you (not yet available)

Instead of opening many browser tabs:

```
hunayn status az                    # how complete is my team?
hunayn reserve gnome-maps main po az
hunayn get gnome-maps main po az    # download the latest PO file
hunayn submit az.po                 # check, then upload
```

Hunayn uses the official Damned Lies REST API with your personal API token,
stored in your system keyring. It never asks for your password.

The final commit to a module's repository stays a human decision on
Damned Lies. Hunayn only helps with the steps before it.

### 2. Check PO files for mistakes before they reach a release

Available now (see [Checking PO files](https://gitlab.com/rehimovv/hunayn#checking-po-files)):

- broken or missing placeholders (`%s`, `%1$d`, `%(name)s`, `{name}`)
- broken or changed markup (`<b>…</b>`, Mallard help tags and links)
- missing, empty or unreadable plural forms
- lost keyboard accelerators (`_File`)

Still to come: terminology that does not match your team's glossary.

Works interactively in the terminal and in GitLab/GitHub CI.

## Built for every language

The core knows nothing about any single language. Each team describes its
own conventions (quotation marks, accelerator style, punctuation, glossary)
in a small data file, kept in a shared
[language repository](https://gitlab.com/rehimovv/hunayn#language-data) where every team maintains its own
folder.

## Language data

Coming soon: a separate `hunayn-languages` repository with one folder per
language code (`az/`, `fr/`, `pt_BR/` …). Hunayn downloads the latest data
when it runs and keeps a local copy for offline use. A team can also point
Hunayn at a glossary in its own repository.

## Roadmap

| Phase | Goal | State |
|-------|------|-------|
| 0 | Preparation: API notes, test corpus, local Damned Lies instance | mostly done |
| 1 | Our own PO parser and writer (byte-identical round trip) | done |
| 2 | Sentinel: first checks (placeholders, tags, plurals) | done: first release on PyPI (0.1.1) |
| 3 | Damned Lies client: status, get, reserve, submit | |
| 4 | Language packs, glossary checks, CI templates → 1.0 | |

## Contributing

Contributions are welcome. See
[CONTRIBUTING.md](https://gitlab.com/rehimovv/hunayn/-/blob/main/CONTRIBUTING.md).
This project follows the
[GNOME Code of Conduct](https://conduct.gnome.org).

## License

Hunayn is free software, licensed under the
[GNU General Public License v3.0 or later](https://gitlab.com/rehimovv/hunayn/-/blob/main/LICENSE).
