Chiedi a Metnos con una richiesta come quella di questo esempio: «Qual è la lingua dell'istanza e qual è lo stato della localizzazione?»

La lingua viene scelta per l'intera istanza durante l'installazione. Una sua modifica è amministrativa, globale e diventa effettiva con un riavvio controllato; non è una preferenza nella scheda di un utente. La fonte persistente è la richiesta firmata in $METNOS_USER_STATE/i18n/localization_request.json; quando è valida prevale sul solo valore iniziale METNOS_LANG.

La lingua è una proprietà dell'istanza. Chat web, Telegram, attività ricorrenti e dispositivi associati consumano lo stesso valore; per servire due lingue contemporaneamente occorrono due istanze Metnos.

1. Il contratto multilingua

Metnos deve mantenere coerenti quattro tipi di contenuto: le istruzioni date ai modelli, le descrizioni degli strumenti, i testi mostrati alle persone e il lessico usato per comprendere le richieste. Tradurre soltanto l'interfaccia non basta: un pulsante può essere in francese mentre il pianificatore legge ancora istruzioni inglesi, oppure la risposta può essere corretta ma il riconoscimento di una formulazione francese può fallire.

Italiano e inglese sono le lingue registrate come pienamente supportate nel codice attuale. Gli archivi possono contenere altre lingue anche durante la traduzione; la loro presenza non prova, da sola, che l'intero prodotto sia pronto in quelle lingue.

Il contratto operativo è il seguente:

• la lingua appartiene all'istanza, non all'utente, al canale o al dispositivo;
• chat web, Telegram e attività ricorrenti ricevono lo stesso valore;
• il contesto di una richiesta può propagare quel valore ma non sostituirlo;
• un testo mancante segue un ripiego dichiarato e non interrompe il servizio;
• una lingua viene dichiarata supportata soltanto dopo traduzione, revisione e prove complete.

2. Come viene stabilita la lingua dell'istanza

L'installer normalizza il codice BCP-47 e registra insieme lingua operativa, eventuale lingua richiesta e stato della localizzazione. Dopo la creazione della chiave dell'installazione, questi dati vengono firmati e sostituiti con una sola scrittura atomica. L'autorità persistente è il documento $METNOS_USER_STATE/i18n/localization_request.json (per impostazione predefinita ~/.local/state/metnos/i18n/localization_request.json). Quando il documento è valido prevale su METNOS_LANG, che resta soltanto il valore iniziale per le installazioni non ancora materializzate.

Al riavvio il runtime verifica il documento firmato e definisce INSTANCE_LANG, REQUESTED_LANG e LOCALIZATION_STATE in un solo modulo di configurazione. Un documento mancante, alterato o malformato non impedisce l'avvio: viene ignorato e resta visibile una diagnostica di ripiego.

Il codice BCP-47 è validato per struttura, senza una lista di lingue cablata. Se la lingua richiesta non è ancora certificata, l'istanza usa temporaneamente l'inglese e conserva l'obiettivo nello stato bootstrap_english. La presenza di alcune traduzioni non abilita da sola la nuova lingua.

3. Le quattro aree da mantenere coerenti

Prompt dei modelli

Ogni chiamante passa esplicitamente un codice lingua al caricatore dei prompt. Se manca un file approvato, il caricatore può usare il candidato presente nella directory _pending; se manca anche quello, ricorre all'inglese. Un candidato non sostituisce un file approvato già presente: per una lingua esistente occorre rivederlo e promuoverlo.

Il pianificatore è composto da un nucleo, sezioni pertinenti e una parte finale. Se nella lingua dell'istanza manca il nucleo, l'intero pianificatore ricorre all'inglese. Se il nucleo esiste ma manca una singola sezione, quella sezione può ricorrere all'equivalente inglese.

Manifest degli executor

[description]
it = "Cerca file per nome, percorso e intervallo temporale."
en = "Find files by name, path, and time window."

[args.properties.patterns.description]
it = "Nomi o espressioni da cercare."
en = "Names or patterns to find."

affinity = ["cerca", "trova", "find", "search", "files"]

Il loader legge direttamente le tabelle del manifest. Le descrizioni non vengono importate nel database dei messaggi. Anche affinity non è una tabella per lingua: è una sola lista di segnali misti, perché serve al riconoscimento semantico e non viene mostrata come testo all'utente. Il file manifest.lang_state.json conserva gli hash necessari all'allineamento, ma non sostituisce il contenuto del manifest.

Testi visibili e lessico di comprensione

I testi deterministici vengono recuperati per chiave dal database i18n. Il campo needs_translation indica il lavoro ancora da svolgere al traduttore; se una riga contiene già un testo non vuoto, quel testo rimane utilizzabile.

Il lessico di comprensione è separato dai testi visibili. Per una lingua nuova, le forme comuni e le associazioni possono essere tradotte in modo assistito; le espressioni regolari restano da redigere e verificare manualmente. In assenza di forme native, Metnos continua a riconoscere le forme italiane e inglesi, ma registra esplicitamente la copertura incompleta.

Per le azioni, superfici e confini non sono più una tabella IT/EN incorporata nel renderer: il mapping versionato vocab.action_surfaces alimenta il riconoscimento e le chiavi VOCAB_ACTION_*_BOUNDARY alimentano i prompt. Il controllo richiede tutte le identità canoniche, testi non vuoti e confini nativi; riporta separatamente le eventuali polisemie da rivedere.

4. Lingua del prompt e lingua della risposta

Un modello tende a seguire la lingua delle istruzioni che riceve, ma non è una garanzia. Non è quindi corretto affidare la lingua della risposta alla sola lingua del prompt.

Metnos passa ai prompt sia il codice della lingua del turno sia il suo nome leggibile. I prompt che producono testo visibile, compresi l'assemblatore finale, le descrizioni e il Tutor, chiedono esplicitamente di scrivere in quella lingua. Di conseguenza un prompt inglese usato come ripiego può ancora chiedere una risposta in francese. Se il codice non è registrato con un nome leggibile, il modello riceve il codice stesso: il turno può funzionare, ma il comportamento è meno affidabile e la lingua non è pronta per il rilascio.

Se un prompt viene scritto nella lingua sbagliata e non contiene l'istruzione sulla lingua d'uscita, il modello può effettivamente rispondere nella lingua del prompt. Le verifiche devono quindi controllare entrambe le cose: scelta corretta del template e indicazione esplicita della lingua della risposta. I messaggi deterministici non dipendono da questo comportamento del modello: seguono sempre la catena del database i18n.

5. Allineamento delle traduzioni

Prompt, descrizioni dei manifest e messaggi registrano l'impronta del testo corrente e quella della versione da cui è stata prodotta una traduzione. Quando viene modificata una lingua, quella versione diventa la sorgente per riallineare le altre.

Il confronto e la scelta delle risorse da aggiornare sono deterministici; il modello interviene soltanto per produrre il testo candidato. La traduzione resta quindi un contenuto generato da rivedere, non una prova automatica di correttezza linguistica.

È opportuno modificare una sola lingua per risorsa prima di eseguire l'allineamento. Nei prompt, modifiche contemporanee vengono risolte in base all'ora del file; in un manifest tutte le lingue condividono lo stesso file e un conflitto viene risolto in ordine alfabetico. Non bisogna affidare a questi criteri due correzioni divergenti.

Il lessico di comprensione segue un ciclo distinto: viene accodato per lingua e verificato con un controllo di copertura. Non partecipa alla scelta della sorgente delle altre tre aree.

6. Aggiungere una lingua

Il comando seguente prepara una lingua, ma non la dichiara supportata. Va eseguito dalla directory runtime con l'ambiente Python dell'installazione di Metnos:

cd <directory-di-installazione>/runtime
../.venv/bin/python -m admin.prompts_cli add-language fr --source-lang=it

Il comando compie tre operazioni immediate:

1. crea runtime/prompts/fr/ e la relativa directory _pending;
2. crea nel database i18n le righe francesi in attesa, a partire dalle chiavi della lingua sorgente;
3. registra, se possibile, l'operazione nel diario multilingua dell'installazione.

Non traduce immediatamente i manifest, non completa il lessico di comprensione, non aggiunge il codice ai registri delle lingue supportate e non cambia la lingua predefinita dell'istanza.

Procedura di rilascio

1. Registrare il codice in vocab.LANGS e aggiungere il nome leggibile della lingua ai registri usati dal caricatore dei prompt e dai traduttori. Verificare anche le parti del vocabolario che espongono forme linguistiche proprie.
2. Eseguire il processo di allineamento, che tratta prompt, descrizioni dei manifest e messaggi:

   ../deploy/run_prompts_translator.sh

3. Preparare il lessico della lingua e tradurre le forme assistite:

   ../.venv/bin/python cli/detection_cli.py enqueue fr
   ../.venv/bin/python cli/detection_cli.py translate

   Ripetere la traduzione finché la coda traducibile è vuota; redigere e verificare manualmente le espressioni regolari rimaste in attesa.
4. Esaminare ogni candidato dei prompt e promuovere soltanto quelli corretti:

   ../.venv/bin/python -m admin.prompts_cli sync-status
   ../.venv/bin/python -m admin.prompts_cli review <ruolo> --lang=fr
   ../.venv/bin/python -m admin.prompts_cli mark-synced <ruolo> --lang=fr

5. Verificare sintassi, simmetria, segnaposto, database e copertura del lessico con i comandi del capitolo successivo.
6. Eseguire una revisione linguistica umana e prove funzionali nella chat web, nei dialoghi, nelle approvazioni, in Settings, su Telegram e nelle attività ricorrenti. Provare anche due istanze con lingue diverse nello stesso momento. Per una lingua da destra a sinistra occorrono inoltre prove visive della direzione, dell'ordine dei controlli e dell'impaginazione.
7. Solo dopo questi controlli attivare la lingua per l'istanza con una modifica amministrativa e un riavvio controllato. METNOS_LANG resta soltanto il valore iniziale quando non esiste ancora una richiesta firmata.

7. Verifiche e strumenti amministrativi

I comandi seguenti si eseguono da <directory-di-installazione>/runtime con ../.venv/bin/python.

Ogni testo visibile nella chat, nei dialoghi, nelle richieste di approvazione e nelle pagine di Settings deve provenire dal catalogo i18n. Una frase scritta direttamente in un template o in JavaScript viola questo contratto anche quando coincide con la lingua predefinita dell'installazione.

Documenti collegati

• Guida all'interfaccia: percorsi della chat web e delle pagine di Settings.
• Guida ai canali: identità, autorizzazioni e resa sui diversi canali.
• Guida agli executor: struttura e ammissione dei manifest.