# Translation status

English (`README.md`) is the source of truth. Everything else here is native human
work, and **nothing on this page is generated by translating prose automatically** —
if a machine rewrote a translator's sentences, the translator would stop translating.

`scripts/check-translations.py` is read-only. It reports drift; a human who reads the
language fixes it.

## Matrix

| Locale | File | Scope | Native reviewer | Translated from | Status | Next action |
|---|---|---|---|---|---|---|
| हिंदी (`hi`) | [README.hi.md](https://github.com/MSKazemi/yazses/blob/main/README.hi.md) | full | [@Sushanttmishraa](https://github.com/Sushanttmishraa) | `96711bc` (2026-08-13) | active | re-check against English when the README changes materially |
| 简体中文 (`zh-CN`) | [README.zh-CN.md](https://github.com/MSKazemi/yazses/blob/main/README.zh-CN.md) | partial | *needed* | `96711bc` (2026-08-13) | active | covers install + quickstart only; a native reviewer is wanted |
| Русский (`ru`) | [README.ru.md](https://github.com/MSKazemi/yazses/blob/main/README.ru.md) | full | [@4nmus](https://github.com/4nmus) | `96711bc` (2026-08-13) | active | re-check against English when the README changes materially |

**Scope** is what the translation claims to cover — `full` (the whole README) or
`partial` (a named subset). A partial translation is not a defect; an *undeclared*
partial translation is, because a reader cannot tell what is missing.

**Status** is one of:

| Status | Meaning |
|---|---|
| `active` | reviewed by a native speaker and believed current |
| `draft` | usable but not yet native-reviewed — must show a visible banner saying so |
| `stale` | known to lag English materially; needs a pass before it is trusted |

## Sync metadata

Every translation carries one HTML comment, directly under the language switcher. It
renders as nothing on GitHub and exists so the checker — and the next translator —
can answer "which English commit was this translated from?":

```html
<!-- yazses-l10n: locale=ru; source=README.md; source_sha=96711bc; scope=full; status=active; reviewer=@4nmus -->
```

| Key | Meaning |
|---|---|
| `locale` | BCP-47-ish tag matching the filename (`README.<locale>.md`) |
| `source` | always `README.md` — English is the source of truth |
| `source_sha` | the short SHA of the English README this was translated from |
| `scope` | `full` or `partial` |
| `status` | `active`, `draft` or `stale` |
| `reviewer` | GitHub handle of the native reviewer, if there is one |

## If you are updating a translation

1. Find what changed in English since your `source_sha`:

   ```bash
   git diff 96711bc..HEAD -- README.md
   ```

2. Translate the prose that changed. **Copy every command, path and URL verbatim** —
   a translated command is the one kind of drift that actively harms a reader, because
   `yazses диагностика` is not a command that exists.
3. Update `source_sha` in your metadata comment to the English commit you just synced
   to, and update your row in the matrix above.
4. Run the checker:

   ```bash
   uv run python scripts/check-translations.py
   ```

   It never edits your file. Exit code 1 means it found something for you to look at.

## If you are adding a new language

Copy `README.md` to `README.<locale>.md`, add your language to the switcher line at
the top of **every** README (including the English one), add the metadata comment, and
add a row to the matrix. Start at `status=draft` with a visible banner near the top
saying the translation has not been native-reviewed yet; the checker enforces that
banner so a reader is never misled about how vetted the text is.

## What the checker does not do

It cannot read your language. It does not judge translation quality, tone, or whether
a sentence still means what the English one means. Those need a human, which is why
the reviewer column exists.