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 dal primo giorno; da settembre 2026 il sistema deve poter accogliere una terza lingua (francese, spagnolo, tedesco) senza toccare il codice.

Il documento copre:

• i tre layer di stringhe (prompt LLM, manifest description executor, messaggi user-facing);
• la disciplina latest-wins: 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 (boot resolve) e source-of-truth (latest-wins, dinamico);
• l'edge case di una traduzione che torna indietro (retro-translate).

Non copre, e demanda altrove:

• la pipeline di traduzione frontier opt-in (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 layer 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 layer seguenti. La separazione è per natura della stringa, non per comodità: nessuna stringa abita due layer.

Layer 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
    … (26 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"). Se manca il file della lingua chiesta, il loader fa fallback alla lingua sorgente (di norma it) e logga un evento prompt.lang_fallback.

Layer 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 nel medesimo folder 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 (companion file)
{
  "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:gemma4-26b",
      "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, fallback IT con log evento.

Layer 3 — messaggi user-facing 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. Source-of-truth: latest-wins

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 triggerare manualmente la traduzione subito:
  /opt/myclaw/deploy/run_prompts_translator.sh

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

Quattro effetti, tutti idempotenti:

1. Layer 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. Layer 2: nessuna azione immediata. Il daemon a ogni cycle scansiona i manifest TOML con tabella [description].fr mancante e genera candidati nel manifest.lang_state.json (campo fr) marcato needs_review=true.
3. Layer 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 a batch.
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 setta METNOS_LANG=fr nei systemd unit del runtime e si riavvia il daemon. Questo evita che frammenti tradotti a metà appaiano in produzione mentre il review umano e' ancora in corso.

5. METNOS_LANG di processo vs source-of-truth 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 al boot dei systemd unit, costante per tutta la vita del processo.

Il source-of-truth (latest-wins 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 source-of-truth 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 latest-wins 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

Layer 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 layer 4 sarà la replica della disciplina layer 1 con sotto-albero channels/templates/<lang>/ e identica meccanica latest-wins. Stima: 8-10 template, 2-3 ore di porting una volta che arriva la terza lingua.

Traduzione frontier opt-in

Il flag --quality {wise,frontier} di metnos-prompts translate e translate-all permette di scegliere il tier LLM. wise e' il default (Gemma 4 26B locale, gratuito); frontier usa Anthropic Opus 4.7 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 opt-in cosciente: niente uso silente di un provider esterno.

Lingue non IRTL e RTL

Arabo, ebraico e persiano richiedono RTL nel rendering HTML dei canali (layer 4 quando arriverà) e attenzione al markup dir="rtl" nei template Jinja2. Layer 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

• ADR 0086 — pattern indices_image: stesso schema di oggetto-strumento + qualifier dominio si applica a indices_text per ricerca semantica multilingua (futuro).
• ADR 0090 — get_inputs: i dialoghi richiedono prompt LLM in lingua del processo per il final_message_hint.
• ADR 0091 — Strato 2 credentials via get_inputs + on_complete: stesso prompt loader, stesse lingue.
• ADR 0092 — prompt-as-data, motivazione e schema completo del layer 1.
• ADR 0093 — build asincrona indici: i progress message escono dal layer 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.