vjrj
7d5f26ff4a
- site: set sourceURL (git.comunes.org/comunes/tane) and weblateURL (translate.comunes.org/projects/tane) — activates footer + collaborate links - app About screen: add 'Source code' and 'Help translate' link tiles - i18n: add about.sourceCode / about.translate / about.translateSubtitle (en base + es/pt/fr/de/ast; ja falls back to base), regenerate slang - docs: add TRANSLATIONS.md runbook for the Weblate app component + git token + slang-regeneration workflow
87 lines
3.8 KiB
Markdown
87 lines
3.8 KiB
Markdown
# 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.
|