Traduzione automatica
Questa pagina è stata tradotta automaticamente dall'IA e potrebbe contenere errori. In caso di dubbi, fare riferimento alla versione inglese.
Internazionalizzazione¶
La documentazione considera l'inglese e il cinese semplificato come fonti canoniche revisionate. Ogni altra lingua abilitata è un derivato generato. Il registro delle lingue, il routing delle fonti, la configurazione del modello e i limiti API si trovano in i18n/config.toml.
1. Copertura linguistica e routing delle fonti¶
Il registro abilita intenzionalmente un insieme mirato di 12 lingue del sito. Copre tutte e sei le lingue ufficiali delle Nazioni Unite: arabo, cinese, inglese, francese, russo e spagnolo. Copre inoltre giapponese, coreano e cinese tradizionale per l'Asia orientale, più tedesco, italiano e portoghese per l'Europa. L'inglese e il cinese semplificato sono canonici, quindi 10 lingue sono tradotte automaticamente.
Giapponese, coreano e cinese tradizionale usano il cinese semplificato come fonte. Tutte le altre lingue generate usano l'inglese. La selezione della fonte è esplicita per lingua; il traduttore non indovina mai dal nome della lingua o dai caratteri del documento.
Aggiungere una lingua richiede voci corrispondenti in i18n/config.toml e nell'elenco delle lingue di MkDocs i18n. Il controllo della documentazione rifiuta registri incoerenti.
2. Contratto del documento canonico¶
Ogni pagina MkDocs ha un file in inglese e un file in .zh-CN.md. Una richiesta pull, un push su main o un'esecuzione di qualità avviata manualmente che modifica una versione canonica deve includere la sua controparte nell'intervallo di commit controllato. Il flusso di lavoro di qualità verifica:
- coppie canoniche e accoppiamento delle coppie modificate;
- parità del livello di intestazione e del recinto di codice;
- collegamenti locali e riferimenti alle fonti;
- inventari di fixture e test;
- una build rigorosa di ogni lingua configurata.
La prosa canonica può essere scritta manualmente o con assistenza AI, ma deve essere impegnata e revisionata come fonte ordinaria. L'API di traduzione non viene mai chiamata da un flusso di lavoro di richiesta pull.
3. Numerazione delle intestazioni e stabilità dei frammenti¶
Il Markdown sorgente memorizza il testo descrittivo dell'intestazione senza numeri di struttura. Durante ogni build MkDocs, scripts/mkdocs_heading_numbers.py aggiunge numeri locali alla pagina alle intestazioni H2–H6. Le pagine della Guida per l'utente usano lettere minuscole per H2 (a., b.) e discendenti lettera-più-decimale (a.1, a.1.1); altre pagine mantengono strutture decimali della pagina. Separatamente, la navigazione a sinistra della Guida per l'utente usa numeri decimali gerarchici come 1.1. I titoli di pagina H1 e le sezioni di navigazione di primo livello rimangono non numerati. I numeri generati sono metadati di presentazione: spostare una sezione cambia il suo numero visibile senza cambiare il suo identificatore di frammento.
L'hook di build rende ogni identificatore di intestazione esplicito prima di aggiungere il numero visibile. i18n/legacy-heading-anchors.json conserva alias per frammenti pubblicati prima che i numeri di struttura memorizzati fossero rimossi. Non modificare quella mappa di compatibilità generata con leggerezza e non aggiungere numeri di struttura manuali al Markdown canonico o generato; il controllo della documentazione li rifiuta.
4. Contratto del documento generato¶
Le pagine generate usano la modalità suffisso di MkDocs, come index.fr.md o guide/configuration.ja.md. Ogni pagina contiene metadati deterministici che registrano:
- la lingua e il percorso della fonte canonica;
- il digest SHA-256 della fonte;
- il modello risolto e la versione del prompt;
- che la pagina è una traduzione automatica.
i18n/manifest.json registra inoltre i digest di output e le impronte digitali dell'input di traduzione. Una pagina diventa obsoleta quando cambiano la sua fonte, il glossario, il prompt, il modello o l'output generato. Il traduttore richiede solo unità obsolete a meno che non venga esplicitamente richiesta una ricostruzione completa.
Le intestazioni tradotte mantengono i loro slug localizzati naturali e ricevono alias nascosti per gli slug canonici della fonte. Poiché le destinazioni dei collegamenti Markdown sono altrimenti protette dalle modifiche del modello, questi alias mantengono validi i collegamenti ai frammenti nella stessa pagina e tra pagine in ogni lingua. Gli alias possono essere aggiornati offline senza un'altra chiamata API di traduzione.
I file generati non devono essere modificati manualmente. Il flusso di lavoro di traduzione del ramo principale li rigenera e checkpoint ogni lingua completata come un commit su un ramo solo generato derivato dallo SHA esatto convalidato per la qualità. Un'esecuzione successiva può verificare e riutilizzare quel ramo, quindi un'interruzione scarta solo la lingua ancora in corso. main rimane invariato fino a quando il flusso di lavoro non ha eseguito il controllo della lingua generata richiesto, la suite di test completa e la build rigorosa di tutte le lingue. Quindi verifica che main non sia avanzato, promuove il checkpoint convalidato con un push fast-forward e distribuisce lo stesso artefatto del sito convalidato.
5. Markdown protetto e contratto del prompt¶
Prima di una richiesta API, il traduttore sostituisce i metadati, il codice racchiuso, il codice inline, le destinazioni dei collegamenti, i tag HTML e gli URL nudi con segnaposto immutabili. Una risposta viene rifiutata se un segnaposto è mancante, duplicato, inventato o spostato al di fuori del contratto di output recuperabile.
Il prompt richiede anche livelli di intestazione identici e linguaggi di recinto di codice. L'implementazione verifica indipendentemente queste proprietà dopo aver ripristinato il contenuto protetto. L'output di traduzione deve essere un oggetto JSON; prosa intorno al JSON, contenuto vuoto, motivi di completamento anomali o schemi incompatibili sono fallimenti.
I prompt di Markdown e del catalogo di navigazione sono versionati sotto i18n/prompts/. i18n/glossary.json contiene terminologia stabile di prodotto e comandi.
6. Configurazione del modello e credenziali¶
Il modello predefinito è configurato come deepseek-v4-flash. L'implementazione non si dirama su quel nome. Una modifica futura del modello richiede solo l'aggiornamento di i18n/config.toml, il passaggio di --model o l'impostazione della variabile del flusso di lavoro DEEPSEEK_TRANSLATION_MODEL. Il modello risolto viene registrato in ogni pagina generata e voce di manifest.
GitHub Actions legge la credenziale API solo dal segreto del repository denominato DEEKSEEK_API_KEY. Viene iniettata solo nel passaggio di generazione quando il piano offline segnala unità in sospeso basate su API. Non è mai disponibile per codice di richiesta pull non attendibile o passaggi di pianificazione, pulizia e convalida senza API. I valori di autenticazione non vengono mai scritti nei log, nei file generati, negli artefatti o nel manifest.
7. Avviso di pagina e preferenza linguistica¶
Le pagine generate automaticamente ricevono un avviso localizzato al momento del rendering. L'avviso identifica la pagina come traduzione AI, collega alla fonte autorevole in inglese o cinese semplificato e collega a un problema di traduzione precompilato. Non fa parte del Markdown tradotto e non crea una voce nell'indice.
Alla prima visita di una pagina radice da parte di un visitatore, il sito confronta navigator.languages con le alternative linguistiche configurate. Una lingua compatibile viene selezionata quando disponibile. Una selezione manuale della lingua viene salvata localmente e ha la precedenza nelle visite successive.
8. Comandi per i manutentori¶
Mostra il numero di unità di traduzione in sospeso senza effettuare chiamate di rete:
uv run python scripts/translate_docs.py --plan
Verifica che ogni pagina generata e catalogo sia aggiornato:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Aggiorna gli alias delle intestazioni sorgente stabili senza chiamate API:
uv run python scripts/translate_docs.py --refresh-heading-anchors
Forza una rigenerazione completa con un modello esplicito:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash