Traducción de Documentación

Traducción de documentación

Este proyecto utiliza el modelo Haiku 3.5 de AWS Bedrock para traducir automáticamente documentación del inglés a múltiples idiomas. El sistema de traducción está diseñado para ser eficiente, preciso y fácil de usar.

Idiomas admitidos

Actualmente, se admiten los siguientes idiomas:

• Japonés (jp)
• Francés (fr)
• Español (es)
• Alemán (de)
• Chino (zh)
• Coreano (ko)

Cómo funciona

El sistema de traducción funciona mediante:

1. División de documentos por encabezados h2 - Permite un procesamiento más eficiente y mejor contexto para el modelo de traducción.
2. Preservación del formato markdown - Toda la sintaxis markdown, bloques de código y etiquetas HTML se conservan durante la traducción.
3. Manejo especial del frontmatter - El frontmatter YAML se traduce manteniendo su estructura.
4. Traducción incremental - Por defecto solo se traducen los archivos modificados, ahorrando tiempo y recursos.

Ejecutar traducciones localmente

Para traducir documentación localmente, utiliza el script scripts/translate.ts:

# Traducir solo archivos modificados a japonés (predeterminado)
./scripts/translate.ts

# Traducir todos los archivos
./scripts/translate.ts --all

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

# Simular traducción sin ejecutarla realmente
./scripts/translate.ts --dry-run

# Mostrar salida detallada
./scripts/translate.ts --verbose

Flujo de trabajo de GitHub

Un workflow de GitHub traduce automáticamente la documentación cuando se realizan cambios en archivos de documentación en inglés dentro de pull requests. El workflow:

1. Detecta cambios en archivos de documentación en inglés
2. Traduce los archivos modificados usando AWS Bedrock
3. Confirma las traducciones en la rama fuente
4. Actualiza el PR con el estado de la traducción

Activación manual del workflow

También puedes activar manualmente el workflow de traducción desde la pestaña GitHub Actions. Esto es útil para:

• Ejecutar una traducción completa de toda la documentación
• Traducir a idiomas específicos
• Actualizar traducciones después de modificar el script de traducción

Configuración de AWS

El sistema de traducción utiliza el modelo Haiku 3.5 de AWS Bedrock. Para usar esta función necesitas:

1. Credenciales de AWS - Para desarrollo local, configura tus credenciales usando AWS CLI o variables de entorno.
2. Rol IAM - Para GitHub Actions, configura un rol IAM con autenticación OIDC y los permisos necesarios para AWS Bedrock.

Permisos requeridos

El rol/usuario IAM necesita los siguientes permisos:

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

Calidad de la traducción

La calidad de traducción es generalmente alta, pero considera:

• Términos técnicos - El sistema está configurado para preservar términos técnicos en inglés.
• Bloques de código - Los bloques de código no se traducen, deben permanecer en su forma original.
• Contexto técnico - El modelo de traducción entiende el contexto técnico de la documentación.

Personalización de la traducción

Puedes personalizar el proceso modificando el archivo scripts/translate.ts. Algunas personalizaciones posibles:

• Añadir soporte para más idiomas
• Cambiar el modelo de traducción
• Ajustar los prompts de traducción
• Modificar cómo se dividen y procesan los documentos

Solución de problemas

Si encuentras problemas con el proceso de traducción:

1. Verifica las credenciales de AWS - Asegúrate de que estén configuradas correctamente.
2. Verifica la región de AWS - Usa una región donde AWS Bedrock esté disponible.
3. Ejecuta con salida detallada - Usa el flag --verbose para ver logs detallados.
4. Verifica límites de tasa - AWS Bedrock tiene límites que pueden afectar trabajos grandes.