Traduje toda mi web en una sola pasada de Claude Code

El trabajo era aburrido e idéntico dieciocho veces: coger cada tutorial en inglés, traducirlo a portugués, soltarlo en la carpeta correcta, añadir una línea al índice. Uno por uno, eso es una tarde que vas a odiar. Pero cada archivo tiene la misma forma, y nada del archivo 7 depende del archivo 3. Esa es la señal: esto debería correr en paralelo, no en fila.

La forma: un agente por archivo

En vez de un agente machacando dieciocho archivos en secuencia, lanzas dieciocho agentes, cada uno dueño de exactamente un archivo. Todos trabajan a la vez. El archivo más lento marca tu tiempo de reloj, no la suma de todos.

La única regla que lo hace funcionar o lo rompe

Aquí está la parte que muerde a la gente, y la razón entera por la que esto merece un tutorial. Que cada agente escriba su propio archivo nuevo es seguro: rutas distintas, sin colisión. Pero los dieciocho también necesitan añadir una línea al mismo archivo de índice. Si dejas que dieciocho agentes escriban ese archivo a la vez, se pisan unos a otros y te queda un desastre corrupto.

Así que no lo haces. Cada agente devuelve su entrada de índice en vez de escribirla. Recoges las dieciocho, y escribes el índice una sola vez, en un solo sitio, cuando terminan. Paraleliza los archivos; serializa el archivo compartido.

// un agente por archivo, todos corriendo a la vez
const entries = await parallel(files.map((f) => () =>
  agent(`Lee ${f}, tradúcelo, escribe la página traducida,
         y devuelve la entrada de índice de este artículo como JSON.`,
        { schema: ENTRY })
));

// LA REGLA: arma el índice compartido UNA vez, justo aquí.
// Nunca dejes que los agentes en paralelo escriban este archivo.
const manifest = JSON.parse(read('tutorials.json'));
manifest.push(...entries.filter(Boolean));
write('tutorials.json', JSON.stringify(manifest, null, 2));

Qué recibe cada agente

El briefing por agente es ajustado e idéntico salvo por el nombre del archivo. Las tres líneas que mantienen la build viva: no toques los bloques de código, corrige la profundidad de los imports, y escribe en la carpeta correcta.

Lee la página en inglés en src/pages/tutorials/<slug>.astro.
Traduce cada frase humana. Deja TODOS los bloques de código byte a byte iguales.
Corrige las rutas de import (el archivo nuevo está una carpeta más profundo: ../../ -> ../../../).
Escribe el resultado en src/pages/<lang>/tutorials/<slug>.astro.
Devuelve la entrada de índice de este artículo como JSON.

Esa línea de "deja los bloques de código byte a byte iguales" importa más de lo que parece. Un agente traductor a su aire va a "mejorar" encantado el nombre de una variable o traducir un comentario de código a algo que ya no corre. Dile que el código está vetado.

Los bugs que me comí (para que tú no)

• El input llegó como texto. Pasé la lista de archivos como dato; el script la recibió como una sola cadena gigante y .map reventó. Una línea lo arregló: parsearla de vuelta a una lista antes de usarla.
• Una build pilló un archivo a medio escribir. Corrí una build mientras los agentes seguían escribiendo. Una página estaba a medio guardar y la build se atragantó. Deja que termine el lote entero, y luego construye una vez.
• Slugs y enlaces cruzados. Si tus páginas traducidas reciben nombres nuevos, los enlaces entre ellas se rompen. Mantuve los nombres de archivo traducidos idénticos bajo una carpeta de idioma, así un enlace es solo un cambio de prefijo que siempre resuelve.

Cuándo merece la pena

No para tres archivos. De cinco para arriba del mismo cambio con la misma forma, el cableado se paga solo: traducir una web, renombrar un patrón por todo un código, reestilizar cada tarjeta, regenerar el metadata de cada página. Cualquier cosa donde el trabajo por archivo sea idéntico y los archivos no dependan unos de otros.

Ahora prueba esto

• Traducir. El caso exacto de aquí: una carpeta de idioma, un agente por página.
• Refactor masivo. "Renombra este hook en todas partes y actualiza los imports", un agente por archivo.
• Metadata en bloque. Genera una descripción SEO para cada página desde su contenido, recogida y escrita una vez.
• Sin escrituras al archivo compartido. Sea cual sea la tarea, encuentra el único archivo que todos quieren tocar y escríbelo tú, después.

Lo que pasó de verdad

Dieciocho páginas, una pasada, unos minutos. Que la IA tradujera cada página no fue la victoria, eso lo hace corras una o dieciocho. La victoria fue hacerlas todas a la vez y negarme a dejar que pelearan por el único archivo que comparten. Paraleliza el trabajo, arma la parte compartida en un solo sitio.