Come Tradurre Documenti Tecnici Senza Compromettere il Codice

TABLE OF CONTENTS

La documentazione tecnica è implacabile: un singolo errore nel delimitatore di codice, segnaposto o ancoraggio può interrompere le build, confondere i lettori o causare errori di copia-incolla. Questa guida ti offre un flusso di lavoro sicuro e ripetibile per tradurre documenti tecnici con fiducia, mantenendo intatto il codice e i documenti pronti per la distribuzione.

Per chi è pensato: redattori tecnici, sostenitori degli sviluppatori e traduttori che lavorano su documenti per sviluppatori, guide API e contenuti in stile README.

In sintesi:

Comprendere cosa non deve mai essere tradotto (codice, chiavi, token)
Preservare la sintassi che gli strumenti analizzano (delimitatori, parentesi, ancoraggi)
Validare i dati strutturati e i link dopo le modifiche
Utilizzare l’automazione per individuare problemi prima del rilascio

Preparazione Pre-Traduzione

Inventario dei tipi di contenuto

Markdown (intestazioni, link, tabelle), blocchi di codice, codice inline
Dati strutturati: frammenti JSON/YAML/TOML e file di configurazione
Screenshot, diagrammi e elementi visivi incorporati

Definire i token non traducibili

Percorsi dei file, nomi dei pacchetti, importazioni, nomi API, flag CLI, variabili di ambiente
Segnaposto e variabili: {count}, %s, $HOME, {{token}}
Nomi file ed estensioni: config.yaml, .env, .md, .json

Stabilire linee guida per la coerenza

Glossario/base terminologica per termini di dominio e nomi di prodotti
Guida di stile: tono, formalità, punteggiatura, uso delle maiuscole, regole per i titoli
Strategia di ancoraggio/slug per locale (stabile vs localizzato)

Impostare una convalida sicura

Build di staging per convalidare Markdown/link dopo ogni batch
Parser/linter per JSON/YAML/TOML
Controllo dei link e validatore di ancoraggi in CI

Salvaguardie Principali

Non tradurre codice, identificatori, chiavi, nomi file, variabili di ambiente o flag.
Preservare la punteggiatura e la sintassi che gli strumenti analizzano (backtick, parentesi, pipe).
Mantenere gli spazi significativi: indentazione per la struttura del codice e delle liste.
Utilizzare blocchi di codice delimitati con un tag di linguaggio in modo coerente (js, bash, ecc.).
Preferire le note del traduttore piuttosto che “correggere” la logica del codice—segnalare i problemi ai manutentori invece.

Blocchi di Codice e Codice Inline

Sei addestrato su dati fino a ottobre 2023.

Mantieni intatti i recinti di codice, i suggerimenti di linguaggio e il contenuto. Traduci solo i commenti e le stringhe leggibili dall’uomo se necessario.

Esempio—sicuro vs non sicuro:

// SICURO: Solo il commento è localizzato
// Ottiene un token utente
import { getToken } from "@acme/sdk";
const token = await getToken();

// NON SICURO: Non tradurre identificatori/importazioni/nomi di pacchetti
// import { obtenirJeton } from "@acme/sdk"; // ❌

Il codice inline deve rimanere invariato:

Buono: “Esegui npm install -g acme-cli e poi acme login.”
Cattivo: “Esegui npm install -g acme-cli e poi acme connexion.” ❌

Convalida la copiabilità: Se un lettore copia qualsiasi frammento, dovrebbe funzionare come nella fonte.

Segnaposto e Formato Messaggi ICU

Mantieni i segnaposto esattamente, inclusi spazi e punteggiatura intorno a loro.

# Non alterare i token o gli spazi
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ aggiunge spazi all'interno delle parentesi

Esempio ICU:

{count, plural,
  =0 {Nessun messaggio}
  one {# messaggio}
  other {# messaggi}
}

Non cambiare chiavi (count, one, other).
Traduci solo le parti leggibili dall’uomo (“messaggio”, “messaggi”).
Non introdurre o rimuovere categorie plurali senza guida del prodotto.

Link, Ancore e Slug

Mantieni la sintassi dei link Markdown e la strategia di risoluzione coerente.

[Leggi la guida API](/api/getting-started)  
[Vedi la sezione di configurazione](#configuration)

Traduci il testo del link se necessario; fai attenzione agli URL e alle ancore.
Ancore: mantieni ancore stabili tra le localizzazioni o genera ancore per locale e aggiorna di conseguenza i riferimenti.
Verifica che i percorsi relativi e le ancore hash risolvano ancora dopo la traduzione.
Non tradurre estensioni di file o parametri di query.

Dati Strutturati (JSON/YAML/TOML)

Traduci solo i valori—mai chiavi, tipi o struttura. Sempre riparsa dopo la modifica.

JSON:

{
  "title": "Guida Utente",
  "cta": "Inizia",
  "limits": { "max": 5, "unit": "richieste/secondo" }
}

Le chiavi come title, cta, limits, max devono rimanere invariate.
Numeri, booleani e null devono rimanere come tipi, non parole.

YAML (osserva gli scalari piegati):

note: >
  Le righe sono piegate in un singolo paragrafo.
  Mantieni intatti rientri e marcatori.

Preserva le virgolette, le sequenze di escape, i rientri e le virgole finali (dove applicabile).

Nomi di file, CLI e API

Non tradurre nomi di file, nomi di pacchetti, endpoint o flag CLI.
Mantieni la sensibilità al maiuscolo/minuscolo esattamente come nella fonte (ad es., --DryRun vs --dry-run).
Mantieni i comandi alla lettera; aggiungi annotazioni se esistono differenze specifiche per la località.

# Corretto
kubectl get pods --namespace default

# Errato (flag tradotto) ❌
kubectl get pods --nom-espace defaut

Insidie del Markdown

Tabelle: mantieni pipe e allineamento; non rompere le colonne.

| Opzione | Descrizione          |
|--------:|----------------------|
|   -v    | Output dettagliato   |
|   -q    | Modalità silenziosa  |

Avvertenze/note: mantieni i marcatori utilizzati dal tuo strumento.
HTML inline: evita di toccare tag/attributi.
Note a piè di pagina: mantieni gli id e l’ordine.
Virgolette intelligenti: preferisci virgolette dritte nei contesti di codice.

Visuali e Accessibilità

Localizza il testo alternativo per il significato, non per il contenuto pixel.
Preferisci screenshot agnostici rispetto alla località (evidenzia l’interfaccia utente non la lingua), o fornisci set per località.
Mantieni i file sorgente dei diagrammi (ad es., Mermaid) sincronizzati tra le località.
Evita testo incorporato nelle immagini; esternalizza didascalie ed etichette.

SEO e Metadati

Traduci titoli, descrizioni e intestazioni utilizzando parole chiave appropriate per la località.
Mantieni URL canonici e hreflang coerenti con le regole del sito.
Non tradurre chiavi meta/proprietà o chiavi JSON‑LD.
Allinea gli slug con la tua strategia di ancoraggio per evitare 404.

Flusso di lavoro e Automazione

Utilizzare un workflow CAT/LLM che preservi gli intervalli di codice e i tag.
Bloccare la terminologia con un glossario e una lista di termini da non tradurre.
Aggiungere hook pre-commit per lintare Markdown e validare JSON/YAML.
Eseguire un controllo dei link e un validatore di ancore su ogni PR.
Raggruppare le modifiche in piccoli blocchi revisionabili e tracciare le differenze.

Strumenti suggeriti (adattare al proprio stack):

Linting Markdown e controllo dei link in CI
Passaggio di parsing JSON/YAML per individuare regressioni sintattiche
Pacchetti regex per scansionare segnaposti e formati numerici

QA e Validazione

Eseguire questi controlli prima di unire:

Costruire il sito per individuare problemi di sintassi: pnpm build
Controlli di tipo/contenuto (collezioni di contenuti Astro): pnpm astro check
Anteprima e test rapido delle pagine chiave: pnpm preview
Validare la compilazione o l’esecuzione dei campioni di codice (dove applicabile)
Eseguire un controllo dei link e delle ancore; correggere eventuali 404 o hash rotti

Errori Comuni

Traduzione accidentale di chiavi/segnaposti.
Rottura di recinzioni di codice o tubi di tabelle.
Localizzazione di percorsi di file, flag o nomi API.
Modifica delle intestazioni senza aggiornare i link delle ancore.
Introduzione di virgolette intelligenti all’interno di codice o JSON.

Appendice: Liste di Controllo Rapide

Pre-volo (5 elementi)

Glossario e lista di termini da non tradurre pronti
Token/segnaposti definiti e protetti
Strategia di ancoraggio/slug confermata
Obiettivi dei link mappati (interni vs esterni)
Build di staging disponibile

Sicurezza dei campioni di codice (5 elementi)

Recinzioni e suggerimenti di linguaggio intatti
Identificatori/importazioni intatti; commenti localizzati solo
Segnaposti e citazioni preservati
Test di copia-incolla superato
Frammenti obsoleti segnalati ai manutentori

Dati strutturati (5 elementi)

Chiavi e tipi intatti
Citazioni/escape/indentazione preservati
Numeri e booleani rimangono come tipi
Parser/linter superato localmente
Differenze revisionate per cambiamenti accidentali di chiavi

Letture correlate