# Translating Tane (Weblate)

Runbook for the translation setup. Written so another agent (or a human) can
reproduce it without prior context.

Tane is translated on **[translate.comunes.org/projects/tane](https://translate.comunes.org/projects/tane/)**
(a self-hosted **Weblate 5.x**, docker-compose at `/data/weblate` on host **tesla**).
The links to the repo and to Weblate are shown both on the landing site
(`site/config.toml` → `sourceURL`, `weblateURL`) and inside the app (About screen).

## What is translatable

| Surface | Files | Format | Base locale | Locales today |
|---|---|---|---|---|
| **App** (`app` component) | `apps/app_seeds/lib/i18n/*.i18n.json` | JSON **nested** (slang, `{param}` placeholders) | `en` | en, es, pt, fr, de, ast, ja |
| **Site** (deferred) | `site/i18n/*.toml` | Hugo TOML | `en` | en, es |

Only source strings live in git; app strings use `slang`, so `strings.g.dart` /
`strings_*.g.dart` are **generated** (see the slang caveat below).

## Git connection

- Repo: `https://git.comunes.org/comunes/tane.git`, branch **`main`** (private
  Gitea/Forgejo behind Cloudflare).
- Weblate must use **HTTPS + an access token** — SSH port 22 is not reachable
  through Cloudflare, so the stored `Comunes Translations` SSH key is unusable here.
- Repository URL in Weblate:
  `https://<user>:<token>@git.comunes.org/comunes/tane.git`
  where `<token>` is a git.comunes.org access token with **read + write** on
  `comunes/tane` (Weblate pushes translations back). Generate it in Gitea/Forgejo
  → Settings → Applications.

## The `app` component (create once)

The `tane` project already exists on Weblate. Add a component (admin UI
*Add new translation component*, or `docker exec weblate-weblate-1 weblate shell`):

| Field | Value |
|---|---|
| Project | `tane` |
| Name / slug | `app` |
| Source code repository | `https://<user>:<token>@git.comunes.org/comunes/tane.git` |
| Repository branch | `main` |
| File mask | `apps/app_seeds/lib/i18n/*.i18n.json` |
| Monolingual base language file | `apps/app_seeds/lib/i18n/en.i18n.json` |
| Template for new translations | `apps/app_seeds/lib/i18n/en.i18n.json` |
| File format | **JSON nested structure** (`json-nested`) — not flat `json` |
| Source language | English (`en`) |

Weblate auto-discovers the existing locales from the mask. Leave push-on-commit on
so translations flow back to `main`.

Sanity check after creating it:
```sh
docker exec weblate-weblate-1 weblate shell -c \
  'from weblate.trans.models import Project; \
   print(Project.objects.get(slug="tane").component_set.count())'   # expect 1
```
Then edit a test string in the UI and confirm a commit lands on
`git.comunes.org/comunes/tane` (`main`) — that validates the token has write.

## slang regeneration caveat (important)

Weblate only edits the `*.i18n.json` sources. The committed `strings.g.dart` /
`strings_*.g.dart` are generated and go **stale** on every Weblate commit, and
there is no CI to regenerate them. Before a release, a maintainer must:

```sh
git pull
cd apps/app_seeds && dart run slang     # regenerates strings*.g.dart
cd ../.. && dart analyze                 # workspace gate
git add -A && git commit -m "chore(i18n): regenerate slang after Weblate sync"
```

(Adding a new source string manually? Same steps — edit `en.i18n.json` first, then
regenerate. `fallback_strategy: base_locale` means locales missing a key show the
English text until translators fill it in.)

## Site component — deferred

Weblate 5.x has no native Hugo-TOML format, and the site has only EN/ES (~3 KB).
Two options, decide later:
- (a) Switch Hugo i18n to a Weblate-supported format (Hugo also reads
  `i18n/*.json` / `*.yaml`), then add a matching `site` component.
- (b) Keep translating the two `site/i18n/*.toml` files by hand.

For now the site is translated manually; only the `app` component is on Weblate.