Tradução de Documentação

Tradução de Documentação

Este projeto utiliza o modelo Haiku 3.5 da AWS Bedrock para traduzir automaticamente documentações do inglês para vários idiomas. O sistema de tradução foi projetado para ser eficiente, preciso e fácil de usar.

Idiomas Suportados

Atualmente, os seguintes idiomas são suportados:

• Japonês (jp)
• Francês (fr)
• Espanhol (es)
• Alemão (de)
• Chinês (zh)
• Coreano (ko)

Como Funciona

O sistema de tradução funciona através das seguintes etapas:

1. Divisão de documentos por cabeçalhos h2 - Permite processamento mais eficiente e melhor contexto para o modelo de tradução.
2. Preservação da formatação markdown - Toda sintaxe markdown, blocos de código e tags HTML são preservados durante a tradução.
3. Manuseio especial do frontmatter - O frontmatter YAML é traduzido enquanto mantém sua estrutura.
4. Tradução incremental - Apenas arquivos alterados são traduzidos por padrão, economizando tempo e recursos.

Executando Traduções Localmente

Para traduzir a documentação localmente, use o script scripts/translate.ts:

# Traduz apenas arquivos alterados para japonês (padrão)
./scripts/translate.ts

# Traduz todos os arquivos
./scripts/translate.ts --all

# Traduz para idiomas específicos
./scripts/translate.ts --languages jp,fr,es

# Simula a tradução sem alterar arquivos
./scripts/translate.ts --dry-run

# Exibe saída detalhada
./scripts/translate.ts --verbose

Fluxo de Trabalho no GitHub

Um fluxo de trabalho do GitHub traduz automaticamente a documentação quando há alterações nos arquivos de documentação em inglês em pull requests. O fluxo de trabalho:

1. Detecta alterações em arquivos de documentação em inglês
2. Traduz os arquivos alterados usando AWS Bedrock
3. Comita as traduções de volta para o branch de origem
4. Atualiza o PR com o status da tradução

Acionamento Manual do Fluxo

Você pode acionar manualmente o fluxo de tradução na aba GitHub Actions. Isso é útil para:

• Executar uma tradução completa de toda a documentação
• Traduzir para idiomas específicos
• Atualizar traduções após alterações no script de tradução

Configuração da AWS

O sistema de tradução utiliza o modelo Haiku 3.5 da AWS Bedrock. Para usar este recurso, você precisa de:

1. Credenciais AWS - Para desenvolvimento local, configure suas credenciais usando AWS CLI ou variáveis de ambiente.
2. Função IAM - Para GitHub Actions, configure uma função IAM com autenticação OIDC e permissões necessárias para AWS Bedrock.

Permissões Necessárias

A função ou usuário IAM precisa das seguintes permissões:

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

Qualidade da Tradução

A qualidade da tradução geralmente é alta, mas alguns pontos importantes:

• Termos técnicos - O sistema preserva termos técnicos em inglês.
• Blocos de código - Blocos de código não são traduzidos, mantendo sua forma original.
• Consciência contextual - O modelo entende o contexto técnico da documentação, melhorando a precisão.

Personalização da Tradução

Você pode personalizar o processo modificando o arquivo scripts/translate.ts. Algumas possibilidades:

• Adicionar suporte a mais idiomas
• Alterar o modelo de tradução
• Ajustar os prompts de tradução
• Modificar a divisão e processamento de documentos

Solução de Problemas

Caso encontre problemas:

1. Verifique credenciais AWS - Confira se estão configuradas corretamente.
2. Verifique região AWS - Use uma região onde o AWS Bedrock está disponível.
3. Execute com saída detalhada - Use a flag --verbose para logs detalhados.
4. Verifique limites de taxa - O AWS Bedrock possui limites que podem afetar grandes jobs.