Traduzione della Documentazione

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:

1. Suddivisione dei documenti per intestazioni h2 - Permette una elaborazione più efficiente e un migliore contesto per il modello di traduzione.
2. Preservazione della formattazione markdown - Tutta la sintassi markdown, i blocchi di codice e i tag HTML vengono preservati durante la traduzione.
3. Gestione speciale del frontmatter - Il frontmatter YAML viene tradotto mantenendo la sua struttura.
4. 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:

1. Rileva le modifiche ai file della documentazione inglese
2. Traduce i file modificati utilizzando AWS Bedrock
3. Invia le traduzioni al branch sorgente
4. 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:

1. Credenziali AWS - Per lo sviluppo locale, configura le credenziali AWS utilizzando la CLI AWS o variabili d’ambiente.
2. 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:

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