Cómo Traducir Documentos Técnicos Sin Romper el Código

TABLE OF CONTENTS

La documentación técnica es implacable: una sola cerca de código rota, marcador de posición o ancla puede romper compilaciones, confundir a los lectores o causar fallos en el copiar y pegar. Esta guía te ofrece un flujo de trabajo seguro y repetible para traducir documentos técnicos con confianza, manteniendo el código intacto y los documentos listos para su envío.

Para quién es: redactores técnicos, defensores de desarrolladores y traductores que trabajan en documentación para desarrolladores, guías de API y contenido al estilo README.

De un vistazo:

Comprende lo que nunca debe traducirse (código, claves, tokens)
Conserva la sintaxis que las herramientas analizan (cercas, llaves, anclas)
Valida datos estructurados y enlaces después de las ediciones
Usa la automatización para detectar problemas antes del lanzamiento

Preparación Previa a la Traducción

Inventario de tipos de contenido

Markdown (encabezados, enlaces, tablas), bloques de código, código en línea
Datos estructurados: fragmentos JSON/YAML/TOML y archivos de configuración
Capturas de pantalla, diagramas y elementos visuales incrustados

Define tokens no traducibles

Rutas de archivos, nombres de paquetes, importaciones, nombres de API, banderas CLI, variables de entorno
Marcadores de posición y variables: {count}, %s, $HOME, {{token}}
Nombres de archivos y extensiones: config.yaml, .env, .md, .json

Establece directrices de consistencia

Glosario/base de términos para términos de dominio y nombres de productos
Guía de estilo: tono, formalidad, puntuación, uso de mayúsculas, reglas de titulares
Estrategia de anclaje/slug por localidad (estable vs localizado)

Configura una validación segura

Construcción de prueba para validar Markdown/enlaces después de cada lote
Analizadores/linter para JSON/YAML/TOML
Verificador de enlaces y validador de anclas en CI

Salvaguardas Principales

No traduzcas código, identificadores, claves, nombres de archivos, variables de entorno o banderas.
Conserva la puntuación y la sintaxis que las herramientas analizan (comillas invertidas, llaves, tuberías).
Mantén el espacio en blanco significativo: sangría para la estructura de código y listas.
Usa bloques de código delimitados con una etiqueta de lenguaje de manera consistente (js, bash, etc.).
Prefiere notas del traductor sobre “corregir” la lógica del código; en su lugar, señala los problemas a los mantenedores.

Bloques de Código y Código en Línea

Mantén los bloques de código, las sugerencias de lenguaje y el contenido intactos. Traduce solo los comentarios y las cadenas legibles por humanos si es necesario.

Ejemplo—seguro vs inseguro:

// SEGURO: Solo se localiza el comentario
// Obtiene un token de usuario
import { getToken } from "@acme/sdk";
const token = await getToken();

// INSEGURO: No traduzcas identificadores/importaciones/nombres de paquetes
// import { obtenirJeton } from "@acme/sdk"; // ❌

El código en línea debe permanecer literal:

Bien: “Ejecuta npm install -g acme-cli y luego acme login.”
Mal: “Ejecuta npm install -g acme-cli y luego acme connexion.” ❌

Valida la capacidad de copiar y pegar: Si un lector copia cualquier fragmento, debería ejecutarse como en la fuente.

Marcadores de posición y formato de mensajes ICU

Conserva los marcadores de posición exactamente, incluyendo el espaciado y la puntuación alrededor de ellos.

# No alteres los tokens ni el espaciado
echo "Procesando {count} archivos"   # ✅
echo "Procesando { count } archivos" # ❌ añade espacios dentro de las llaves

Ejemplo de ICU:

{count, plural,
  =0 {No hay mensajes}
  one {# mensaje}
  other {# mensajes}
}

No cambies las claves (count, one, other).
Traduce solo las partes legibles por humanos (“mensaje”, “mensajes”).
No introduzcas ni elimines categorías plurales sin la guía del producto.

Enlaces, anclas y slugs

Mantén la sintaxis de enlaces de Markdown y la estrategia de resolución consistente.

[Lee la guía de la API](/api/getting-started)  
[Consulta la sección de configuración](#configuration)

Traduce el texto del enlace si es necesario; ten cuidado con las URLs y anclas.
Anclas: mantén anclas estables en todos los idiomas o genera anclas por idioma y actualiza las referencias en consecuencia.
Verifica que las rutas relativas y las anclas de hash aún se resuelvan después de la traducción.
No traduzcas extensiones de archivos o parámetros de consulta.

Datos estructurados (JSON/YAML/TOML)

Traduce solo los valores—nunca las claves, tipos o estructura. Siempre vuelve a analizar después de editar.

JSON:

{
  "title": "Guía del usuario",
  "cta": "Comenzar",
  "limits": { "max": 5, "unit": "solicitudes/segundo" }
}

Claves como title, cta, limits, max deben permanecer sin cambios.
Los números, booleanos y nulos deben mantenerse como tipos, no como palabras.

YAML (observe los escalar plegados):

note: >
  Las líneas se pliegan en un solo párrafo.
  Mantenga la sangría y los marcadores intactos.

Conserve las comillas, los escapes, la sangría y las comas finales (donde corresponda).

Nombres de archivos, CLI y API

No traduzca nombres de archivos, nombres de paquetes, endpoints o banderas de CLI.
Mantenga la sensibilidad a mayúsculas y minúsculas exactamente como en la fuente (por ejemplo, --DryRun vs --dry-run).
Mantenga los comandos textualmente; agregue notas si existen diferencias específicas del idioma.

# Correcto
kubectl get pods --namespace default

# Incorrecto (bandera traducida) ❌
kubectl get pods --nom-espace defaut

Trampas de Markdown

Tablas: mantenga las tuberías y la alineación; no rompa las columnas.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Advertencias/notas: conserve los marcadores utilizados por su herramienta.
HTML en línea: evite tocar etiquetas/atributos.
Notas al pie: mantenga los ids y el orden.
Comillas inteligentes: prefiera comillas rectas dentro de contextos de código.

Visuales y Accesibilidad

Localice el texto alternativo por significado, no por contenido de píxeles.
Prefiera capturas de pantalla independientes del idioma (resalte la interfaz de usuario, no el idioma), o proporcione conjuntos por idioma.
Mantenga los archivos fuente de diagramas (por ejemplo, Mermaid) sincronizados entre idiomas.
Evite texto incrustado en imágenes; externalice subtítulos y etiquetas.

SEO y Metadatos

Traduza títulos, descripciones y encabezados utilizando palabras clave apropiadas para el idioma.
Mantenga las URL canónicas y hreflang consistentes con las reglas del sitio.
No traduzca claves de meta/propiedad o claves de JSON‑LD.
Alinee los slugs con su estrategia de anclaje para evitar 404s.

Flujo de trabajo y Automatización

Utiliza un flujo de trabajo CAT/LLM que preserve los fragmentos de código y etiquetas.
Bloquea la terminología con un glosario y una lista de no traducir.
Añade hooks de pre‑commit para limpiar Markdown y validar JSON/YAML.
Ejecuta un verificador de enlaces y un validador de anclajes en cada PR.
Agrupa los cambios en pequeños fragmentos revisables y sigue los diffs.

Herramientas sugeridas (adapta a tu stack):

Limpieza de Markdown y verificación de enlaces en CI
Paso de análisis de JSON/YAML para detectar regresiones de sintaxis
Paquetes de expresiones regulares para escanear marcadores de posición y formatos numéricos

QA y Validación

Ejecuta estas comprobaciones antes de fusionar:

Construye el sitio para detectar problemas de sintaxis: pnpm build
Comprobaciones de tipo/contenido (colecciones de contenido de Astro): pnpm astro check
Previsualiza y realiza pruebas puntuales en páginas clave: pnpm preview
Valida que los ejemplos de código se compilen o ejecuten (donde sea aplicable)
Ejecuta un verificador de enlaces y anclajes; corrige cualquier 404 o hashes rotos

Errores Comunes

Traducir claves/marcadores de posición por accidente.
Romper cercas de código o tuberías de tablas.
Localizar rutas de archivos, banderas o nombres de API.
Cambiar encabezados sin actualizar los enlaces de anclaje.
Introducir comillas inteligentes dentro de código o JSON.

Apéndice: Listas de Verificación Rápidas

Pre‑vuelo (5 elementos)

Glosario y lista de no traducir listos
Tokens/marcadores de posición definidos y protegidos
Estrategia de anclaje/slug confirmada
Objetivos de enlace mapeados (internos vs externos)
Construcción de staging disponible

Seguridad de ejemplos de código (5 elementos)

Cercas y sugerencias de lenguaje intactas
Identificadores/importaciones sin tocar; comentarios solo localizados
Marcadores de posición y comillas preservadas
Prueba de copiar‑pegar aprobada
Fragmentos desactualizados señalados a los mantenedores

Datos estructurados (5 elementos)

Claves y tipos sin tocar
Comillas/escapes/indentación preservados
Números y booleanos permanecen como tipos
Analizador/linter pasa localmente
Diffs revisados para cambios accidentales de claves

Lectura relacionada