Chiedi a Metnos con una richiesta come quella di questo esempio: «Qual è la lingua impostata per il mio account e dove posso cambiarla?»

Chi amministra l'istanza può cambiarla nella chat web seguendo Settings > Sistema > Utenti > nome dell'utente > Preferenze, quindi scegliendo il valore del campo lang. La pagina dell'utente risponde all'indirizzo /admin/users/<id-utente>. Se la domanda viene fatta da Telegram, il percorso indicato si trova comunque nella chat web di Metnos, non dentro Telegram.

La lingua è una preferenza di ciascun utente e viene applicata alla singola richiesta. Due utenti possono usare contemporaneamente lingue diverse senza modificare la configurazione globale dell'istanza e senza influenzarsi a vicenda.

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'utente autorizzato, non al dispositivo;
• la stessa preferenza vale nella chat web e nei canali associati a quell'utente;
• ogni richiesta conserva il proprio contesto linguistico fino alla risposta finale;
• 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 scelta la lingua di una richiesta

Nella chat web il server identifica l'utente autenticato e legge la sua preferenza lang. Telegram fa lo stesso partendo dall'associazione fra il canale e l'utente. Anche le attività ricorrenti eseguite per conto di una persona applicano la lingua del relativo proprietario.

Il valore viene inserito in un contesto locale alla richiesta. Questo contesto è isolato anche quando più turni vengono eseguiti in parallelo: impostare l'inglese per un utente non cambia la lingua di un altro utente né quella del processo.

Le lingue proposte dal campo lang non provengono da una lista scritta nella pagina: vengono ricavate dalle lingue presenti nel catalogo i18n.sqlite. Per questo il comando di preparazione di una nuova lingua può renderla selezionabile prima che tutte le traduzioni siano state completate. I ripieghi mantengono il servizio utilizzabile, ma l'amministratore non dovrebbe offrirla agli utenti prima delle verifiche descritte più avanti.

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 richiesta 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.

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 utenti 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 offrire la lingua agli utenti. Il campo lang ricava automaticamente i valori dal catalogo i18n; non richiede una lista separata nella pagina. Impostare METNOS_LANG è facoltativo e cambia soltanto il ripiego dell'istanza, non le preferenze individuali.

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.