I translated my whole site in one Claude Code run

The job was boring and identical eighteen times: take each English tutorial, translate it to Portuguese, drop it in the right folder, add a line to the index. One by one, that's an afternoon you'll resent. But every file is the same shape, and nothing about file 7 depends on file 3. That's the signal: this should run in parallel, not in a line.

The shape: one agent per file

Instead of one agent grinding through eighteen files in sequence, you spawn eighteen agents, each owning exactly one file. They all work at the same time. The slowest single file sets your wall-clock, not the sum of all of them.

The one rule that makes or breaks it

Here's the part that bites people, and the whole reason this is worth a tutorial. Each agent writing its own new file is safe: different paths, no collision. But all eighteen also need to add a line to the same index file. If you let eighteen agents write that one file at once, they stomp on each other and you get a corrupted mess.

So you don't. Each agent returns its index entry instead of writing it. You collect all eighteen, and write the index once, in one place, after they finish. Parallelize the files; serialize the shared file.

// one agent per file, all running at the same time
const entries = await parallel(files.map((f) => () =>
  agent(`Read ${f}, translate it, write the translated page,
         and return this article's index entry as JSON.`,
        { schema: ENTRY })
));

// THE RULE: assemble the shared index ONCE, right here.
// Never let the parallel agents write this file.
const manifest = JSON.parse(read('tutorials.json'));
manifest.push(...entries.filter(Boolean));
write('tutorials.json', JSON.stringify(manifest, null, 2));

What each agent gets

The brief per agent is tight and identical except for the filename. The three lines that keep the build alive: keep code blocks untouched, fix the import depth, and write to the right folder.

Read the English page at src/pages/tutorials/<slug>.astro.
Translate every human sentence. Keep ALL code blocks byte-identical.
Fix the import paths (the new file sits one folder deeper: ../../ -> ../../../).
Write the result to src/pages/<lang>/tutorials/<slug>.astro.
Return this article's index entry as JSON.

That "keep code blocks byte-identical" line matters more than it looks. A translator agent left alone will happily "improve" a variable name or translate a code comment into something that no longer runs. Tell it the code is off-limits.

The bugs I hit (so you don't)

• The input arrived as text. I passed the list of files as data; the script received it as one big string and .map blew up. One line fixed it: parse it back into a list before using it.
• A build caught a half-written file. I ran a build while the agents were still writing. One page was mid-save and the build choked. Let the whole batch finish, then build once.
• Slugs and cross-links. If your translated pages get new names, links between them break. I kept the translated filenames identical under a language folder, so a link is just a prefix swap that always resolves.

When it's worth it

Not for three files. For five and up of the same-shaped change, the wiring pays for itself: translate a site, rename a pattern across a codebase, restyle every card, regenerate every page's metadata. Anything where the work per file is identical and the files don't depend on each other.

Now try this

• Translate. The exact case here: one language folder, one agent per page.
• Mass refactor. "Rename this hook everywhere and update the imports," one agent per file.
• Bulk metadata. Generate an SEO description for every page from its content, collected and written once.
• No shared-file writes. Whatever the task, find the one file everyone wants to touch and write it yourself, after.

What actually happened

Eighteen pages, one run, a few minutes. The AI translating each page wasn't the win, it does that whether you run one or eighteen. The win was doing all of them at once and refusing to let them fight over the one file they all share. Parallelize the work, assemble the shared part in a single place.