tane/TRANSLATIONS.md

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 (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:

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:

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.