Traduzione della Documentazione

Questo progetto utilizza il modello Haiku 3.5 di AWS Bedrock per tradurre automaticamente la documentazione dall’inglese a più lingue. Il sistema di traduzione è progettato per essere efficiente, accurato e semplice da utilizzare.

Lingue Supportate

Attualmente sono supportate le seguenti lingue:

Giapponese (jp)
Francese (fr)
Spagnolo (es)
Tedesco (de)
Cinese (zh)
Coreano (ko)

Funzionamento

Il sistema di traduzione funziona:

Suddivisione dei documenti per intestazioni h2 - Permette una elaborazione più efficiente e un migliore contesto per il modello di traduzione.
Preservazione della formattazione markdown - Tutta la sintassi markdown, i blocchi di codice e i tag HTML vengono preservati durante la traduzione.
Gestione speciale del frontmatter - Il frontmatter YAML viene tradotto mantenendo la sua struttura.
Traduzione incrementale - Per impostazione predefinita vengono tradotti solo i file modificati, risparmiando tempo e risorse.

Esecuzione delle Traduzioni in Locale

Per tradurre la documentazione in locale, utilizza lo script scripts/translate.ts:

# Traduce solo i file modificati in giapponese (predefinito)
./scripts/translate.ts

# Traduce tutti i file
./scripts/translate.ts --all

# Traduce in lingue specifiche
./scripts/translate.ts --languages jp,fr,es

# Mostra le operazioni di traduzione senza eseguirle
./scripts/translate.ts --dry-run

# Mostra output dettagliato
./scripts/translate.ts --verbose

Workflow GitHub

Un workflow GitHub traduce automaticamente la documentazione quando vengono apportate modifiche ai file della documentazione inglese nelle pull request. Il workflow:

Rileva le modifiche ai file della documentazione inglese
Traduce i file modificati utilizzando AWS Bedrock
Invia le traduzioni al branch sorgente
Aggiorna la PR con lo stato della traduzione

Attivazione Manuale del Workflow

È possibile attivare manualmente il workflow di traduzione dalla scheda GitHub Actions. Utile per:

Eseguire una traduzione completa di tutta la documentazione
Tradurre in lingue specifiche
Aggiornare le traduzioni dopo modifiche allo script di traduzione

Configurazione AWS

Il sistema di traduzione utilizza il modello Haiku 3.5 di AWS Bedrock. Per utilizzare questa funzionalità, è necessario:

Credenziali AWS - Per lo sviluppo locale, configura le credenziali AWS utilizzando la CLI AWS o variabili d’ambiente.
Ruolo IAM - Per GitHub Actions, configura un ruolo IAM con autenticazione OIDC e le autorizzazioni necessarie per AWS Bedrock.

Autorizzazioni Richieste

Il ruolo o utente IAM richiede le seguenti autorizzazioni:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}

Qualità della Traduzione

La qualità della traduzione è generalmente elevata, ma è importante considerare:

Termini tecnici - Il sistema è configurato per preservare i termini tecnici in inglese.
Blocchi di codice - I blocchi di codice non vengono tradotti, poiché devono rimanere nella forma originale.
Consapevolezza del contesto - Il modello di traduzione comprende il contesto della documentazione, migliorando le traduzioni tecniche.

Personalizzazione della Traduzione

È possibile personalizzare il processo di traduzione modificando il file scripts/translate.ts. Alcune personalizzazioni includono:

Aggiunta del supporto per altre lingue
Modifica del modello di traduzione
Regolazione dei prompt di traduzione
Modifica della suddivisione e elaborazione dei documenti

Risoluzione dei Problemi

In caso di problemi con il processo di traduzione:

Verifica le credenziali AWS - Assicurati che siano configurate correttamente.
Verifica la regione AWS - Utilizza una regione dove AWS Bedrock è disponibile.
Esegui con output dettagliato - Usa il flag --verbose per log più approfonditi.
Controlla i limiti di frequenza - AWS Bedrock applica limiti che potrebbero influenzare lavori di traduzione massicci.