1. Scopo e confini

Questo documento definisce come Metnos parla più lingue: dove vivono le stringhe, chi può modificarle, come si propaga un cambio da una lingua all'altra, come si aggiunge una nuova lingua. Italiano e inglese sono entrambi presenti; il sistema deve poter accogliere una terza lingua (francese, spagnolo, tedesco) senza toccare il codice.

Il documento copre:

• i tre strati di stringhe (prompt LLM, manifest description executor, messaggi rivolto all'utente);
• la disciplina vince l'ultimo: nessuna lingua è canonica per costruzione, vince chi viene editato per ultimo;
• il comando admin metnos-prompts add-language <code> e i suoi effetti;
• la differenza fra METNOS_LANG di processo (risoluzione all'avvio) e fonte di verità (vince l'ultimo, dinamico);
• il caso limite di una traduzione che torna indietro (retro-translate).

Non copre, e demanda altrove:

• la pipeline di traduzione di frontiera facoltativa (prompt provider-specifici): vedi synt §4.2.3 per il pattern repertoire;
• la rotazione del DB i18n (vacuum, retention): vedi runtime/i18n.py;
• il rendering dei template HTML di canale (Telegram + HTTP): vedi channel.

2. I tre strati multilingua

Ogni stringa che Metnos pronuncia, o che un LLM legge come parte di una sua istruzione, vive in uno e un solo dei tre strati seguenti. La separazione è per natura della stringa, non per comodità: nessuna stringa abita due strati.

Strato 1 — prompt LLM

La directory runtime/prompts/ ha un sotto-albero per lingua. Ogni ruolo (planner, vaglio_judge, describe_entries, …) è un file .j2 con stessa struttura in ogni lingua: stesse variabili, stessa intelaiatura di sezioni, solo testo localizzato.

runtime/prompts/
 it/
 planner.j2
 vaglio_judge.j2
 describe_entries.j2
 … (32 file)
 en/
 planner.j2 # stessa intelaiatura, testo in EN
 …
 _pending/
 planner.j2.candidate # candidato in attesa di review
 fr/ # opzionale, dopo metnos-prompts add-language fr
 …

Il loader runtime/prompt_loader.py è chiamato da ogni componente runtime con prompt_loader.get(role, lang, **vars). Lingua risolta come os.environ["METNOS_LANG"], fallback config.DEFAULT_LANG (oggi "it"). Catena di risoluzione per file (§K, ADR 0173): live → candidato _pending (usato in-vivo) → EN. Se manca il file della lingua chiesta, il loader usa il candidato del daemon se presente, altrimenti ricade su EN (default nel frattempo) — mai crash. Nessuna promozione manuale necessaria.

Strato 2 — manifest description executor

Il manifest TOML di un executor (executors/<name>/manifest.toml) ha la sezione [description] a tabella per lingua, e un companion JSON manifest.lang_state.json nella medesima cartella per tenere traccia di chi e' source e quando.

# manifest.toml
[description]
it = """
Cerca file su filesystem per pattern e finestra temporale.
…
"""
en = """
Find files on the filesystem by pattern and time window.
…
"""

[affinity]
it = ["cerca", "trova", "file", "ricerca", "…"]
en = ["find", "search", "files", "lookup", "…"]

// manifest.lang_state.json (file companion)
{
 "lang_state": {
 "it": {
 "version_hash": "a3f9...",
 "source_hash": null, // it = source corrente
 "source_lang": null,
 "translated_by": null,
 "reviewed_at": "2026-04-22T10:30Z"
 },
 "en": {
 "version_hash": "7c1b...",
 "source_hash": "a3f9...", // EN derivato da hash IT a3f9
 "source_lang": "it",
 "translated_by": "wise:qwen3.6-35b-a3b",
 "reviewed_at": "2026-04-22T11:05Z"
 }
 }
}

A run time il pianificatore legge la description nella lingua corrente (METNOS_LANG) via loader.describe(name, lang); se la lingua manca, ripiego a EN esplicito (§K, ADR 0173), altrimenti prima lingua disponibile.

Strato 3 — messaggi rivolto all'utente in i18n.sqlite

Il modulo runtime/i18n.py espone i18n.get(key, lang=None, **vars) con interpolazione stile {name}. Le chiavi seguono la convenzione SCOPE_DOMAIN_DETAIL: ERR_FILE_NOT_FOUND, WARN_CAP_REACHED, MSG_APPROVAL_GRANTED, LOG_TURN_ENDED.

Le description degli executor sono tutte migrate nel DB con prefisso EX_DESCRIPTION_<name> e EX_AFFINITY_<name>; il loader del manifest le legge dal DB invece che dal TOML. Il TOML resta autoritativo per i nuovi executor; il DB le importa al primo load.

3. Fonte di verità: vince l'ultimo

Nessuna lingua e' canonica per costruzione. Chi e' stato editato per ultimo (in qualunque lingua) diventa source per le altre.

Per ogni risorsa multilingua — un prompt, una description, una chiave i18n — teniamo due hash:

• version_hash — SHA-256 del testo corrente nella sua lingua;
• source_hash — version_hash della lingua sorgente al momento dell'ultimo allineamento. null se la lingua è essa stessa la sorgente corrente.

Trigger del re-allineamento

Quando un editor (umano o batch) cambia il testo della lingua L1 di una risorsa, il version_hash di L1 cambia. Questo invalida implicitamente tutte le altre lingue L2, L3, … che hanno source_hash uguale al vecchio version_hash di L1: non sono più sincronizzate. Il daemon notturno i18n_translator.run_loop le ritrova come pending e genera un nuovo candidato in _pending/.

Determinismo del confronto (no LLM nel critical path)

Il confronto version_hash vs source_hash è deterministico (CLAUDE.md §7.9). L'LLM interviene solo per generare il candidato di traduzione; il quando rigenerare e il quale e' la sorgente sono codice puro, niente prompt.

4. Workflow add-language

Il flusso completo per aggiungere una nuova lingua è un comando solo:

$ metnos-prompts add-language fr
Lingua 'fr' bootstrap completato.
 - prompts/fr/ creata (vuota, daemon notturno generera' candidate)
 - i18n.sqlite: fr bootstrap rows pending
 - Manifest description: il daemon scansionera' al prossimo cycle

Per innescare manualmente la traduzione subito:
 /opt/metnos/deploy/run_prompts_translator.sh

Per attivare la lingua: METNOS_LANG=fr nei systemd unit + restart

Quattro effetti, tutti idempotenti:

1. Strato 1: crea runtime/prompts/fr/ vuota. Il daemon notturno la riempirà con candidati a partire dalla lingua sorgente (default it; specificabile con --source-lang en se EN e' diventata la lingua piu' aggiornata).
2. Strato 2: nessuna azione immediata. Il daemon a ogni ciclo scansiona i manifest TOML con tabella [description].fr mancante e genera candidati nel manifest.lang_state.json (campo fr) marcato needs_review=true.
3. Strato 3: i18n_cli.add-lang fr popola la tabella i18n con un placeholder per ogni chiave esistente, needs_translation=1, source_lang=it. Il daemon traduce in lotti.
4. Audit: scrive una entry in ~/.local/share/metnos/multilang/audit.jsonl con timestamp, codice ISO, source_lang scelta.

La lingua resta inattiva finché non si imposta METNOS_LANG=fr nei systemd unit del runtime e si riavvia il daemon. Finché una stringa non è tradotta, il runtime ricade su EN (default nel frattempo), mai su frammenti rotti.

5. METNOS_LANG di processo vs fonte di verità dinamico

METNOS_LANG e' la lingua di lettura del processo: quale lingua il pianificatore vede come prompt, quale lingua compare nei messaggi all'utente. E' una variabile statica, risolta all'avvio dei systemd unit, costante per tutta la vita del processo.

Il fonte di verità (vince l'ultimo di §3) e' un attributo dinamico per risorsa: per la risorsa A può essere IT, per la B EN, per la C FR — dipende da chi ha editato per ultimo. Il daemon translator usa il fonte di verità per decidere da-cosa-tradurre-cosa, indipendentemente da METNOS_LANG.

6. Edge case: retro-translate manuale

Capita che un editor preferisca scrivere una nuova versione di un prompt direttamente nella lingua secondaria (es. EN), per poi voler riportare la modifica in IT. Il vince l'ultimo lo fa automaticamente: quando l'edit EN va in commit, il version_hash(en) diventa nuovo, EN diventa source corrente, e la notte successiva il candidato IT viene rigenerato in prompts/it/_pending/<role>.j2.candidate.

Lo stesso comando di review/mark-synced funziona simmetrico: metnos-prompts review planner --lang=it mostra il diff, mark-synced planner --lang=it promuove. La direzione di traduzione e' codificata nel source_lang del companion JSON, non nel verso del comando.

7. Estensioni future

Strato 4 — HTML templates di rendering chat

Oggi i template Jinja2 di channels/templates/ (carta di approval, dialog form, summary di turno) sono solo IT. Il strato 4 sarà la replica della disciplina strato 1 con sotto-albero channels/templates/<lang>/ e identica meccanica vince l'ultimo. Stima: 8-10 template, 2-3 ore di adattamento una volta che arriva la terza lingua.

Traduzione di frontiera facoltativa

Il flag --quality {wise,frontier} di metnos-prompts translate e translate-all permette di scegliere il tier LLM. wise e' il default (modello locale, gratuito); frontier usa Anthropic Opus 4.8 con costo ~$0.015/call. La differenza emerge sui prompt lunghi e sui ruoli (es. vaglio_judge) dove la sfumatura semantica e' alta. Documentato nel man del CLI come scelta cosciente: niente uso silente di un provider esterno.

Lingue non IRTL e RTL

Arabo, ebraico e persiano richiedono RTL nel rendering HTML dei canali (strato 4 quando arriverà) e attenzione al markup dir="rtl" nei template Jinja2. Strato 1-3 sono RTL-agnostici: le stringhe sono solo testo, il canale e' responsabile del rendering.

8. CLI di riferimento

Il manifest centrale di installazione (install/manifest.toml) non elenca le lingue: sono dati persistiti, non capability. Aggiungere FR non modifica i systemd unit né il manifest, solo METNOS_LANG=fr al momento di attivarla.

Riferimenti

• Pattern indices_image: stesso schema di oggetto-strumento + qualifier dominio si applica a indices_text per ricerca semantica multilingua (futuro).
• get_inputs: i dialoghi richiedono prompt LLM in lingua del processo per il final_message_hint.
• Strato 2 credentials via get_inputs + on_complete: stesso prompt loader, stesse lingue.
• Prompt-as-data: motivazione e schema completo del strato 1.
• Build asincrona indici: i progress message escono dallo strato 3 (i18n.sqlite), naturalmente localizzati.
• Codice: runtime/prompt_loader.py, runtime/i18n.py, runtime/i18n_translator.py, runtime/admin/prompts_cli.py, runtime/admin/i18n_cli.py.