How to build and maintain a multilingual website with Claude Code

Claude Code can do most of the engineering on a multilingual website: set up a separate URL for each language, generate hreflang tags from one map so they never fall out of step, set the page language attribute, build a language switcher, translate metadata and structured data along with the body, and run checks that catch broken or one-way hreflang links. It can also draft translations from a glossary you provide. What it can't do is vouch for a translation. A fluent person who knows your business reviews every page before it's published.

That review isn't optional politeness. Google's guidance on AI content says that "using generative AI tools or other similar tools to generate many pages without adding value for users may violate Google's spam policy on scaled content abuse", and its spam policies name "automated transformations like synonymizing, translating" among the ways scraped content gets turned into many low-value pages. Publishing hundreds of unreviewed machine translations moves a site toward that line, and readers notice bad translations long before any policy does.

Step 1: decide languages and markets as a business

Google distinguishes two cases. A multilingual site "offers content in more than one language", such as a Canadian business with English and French pages. A multi-regional site "explicitly targets users in different countries". Some sites are both. Decide which you are, which languages and countries you'll serve, and who will review each language. If nobody on your side can review a language, think twice before publishing it.

Step 2: choose a URL structure

Each language version needs its own URL. Google lists these options.

Our advice for most small and mid-sized business sites is subdirectories, because they keep one domain, one host and one codebase. The choice is yours, and it's expensive to change later, so make it before Claude Code builds anything.

Avoid switching languages with cookies or by detecting the visitor's settings. Google warns that if you reroute users dynamically, "Google might not find and crawl all your variations", because its crawler "usually originates from the USA" and sends requests "without setting Accept-Language".

Step 3: set up a translation workflow

Good translation with Claude Code starts with written rules, not with a prompt.

• A glossary. Your product names, service names and key terms in each language, with the approved translation, or a note to leave them in English.
• A style note per language. Formal or informal address, date and number formats, currency, units.
• A do-not-translate list. Brand names, legal entity names, quoted text.
• Scope. The body, title, meta description, image alt text, button labels, form messages, error pages and the text inside structured data.

Keep these in files in the repository, and point to them from your project's CLAUDE.md so every session uses them. Our guide to writing a CLAUDE.md for a website explains how.

Example prompt: Translate the five pages in pages/en/services into Spanish for es/ using glossary-es.md and style-es.md. Translate the title, meta description, alt text and any text inside structured data as well as the body. List every term you weren't sure about and every sentence where the meaning could change. Don't publish anything.

A person reviews: every translated page, read by a fluent speaker who knows the business, plus the uncertainty list. For legal, medical or financial content, that reviewer should be qualified in the subject too. Our article on AI-generated versus human-edited content covers why the edit matters.

Keep each page in one language. Google says it uses "the visible content of your page to determine its language" and advises against side-by-side translations. It also warns that translating only the boilerplate, such as menus and footers, while the main content stays in another language "can create a bad user experience".

Step 4: generate hreflang from one map

hreflang annotations tell Google which pages are language or region versions of each other. Google supports three equivalent methods, HTML tags, HTTP headers or the sitemap, and says using all three gives "no benefit in Search". Pick one.

The reliable way to keep hreflang correct is to store the relationships once, in a mapping file that says which English page matches which Spanish and French page, and have the build generate every tag from it. For the HTML method, each page gets the same set of link elements in its head, one per version, including itself:

<link rel="alternate" hreflang="en" href="https://example.com/services/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/servicios/" />
<link rel="alternate" href="https://example.com/services/" hreflang="x-default" />

The rules from Google's hreflang documentation that cause most errors:

• Every version lists itself and all other versions.
• Links must go both ways, or Google ignores them.
• URLs must be fully qualified, with https, not relative paths.
• Codes must be ISO 639-1 languages, optionally with ISO 3166-1 Alpha 2 regions. es-419 isn't supported, and a country code alone isn't allowed.
• The reserved x-default value covers visitors whose language doesn't match any version.

Example prompt: Create translations.json mapping each English page to its Spanish and French versions. Generate hreflang link tags for every page from that file at build time, including a self-reference and an x-default pointing to the English version of the same page. Remove any hand-written hreflang tags. Show me the generated tags for three pages.

Step 5: set the lang attribute and translate the details

Google says it doesn't use "code-level language information such as lang attributes" to detect language. Set the lang attribute anyway: WCAG 2.2 success criterion 3.1.1, Language of Page, requires that "The default human language of each web page can be programmatically determined", so screen readers pronounce the text correctly. Our guide to accessibility fixes with Claude Code covers this and related checks.

Then check the small things that are easy to leave in English: the cookie banner, form validation messages, the 404 page, date formats, and the language name in the switcher. If a fact such as a phone number or address differs by country, store it once per locale and change it with our routine for changing a fact everywhere on your site.

Step 6: let visitors choose their language

Google is direct: "Avoid automatically redirecting users from one language version of a site to a different language version". It also says "Don't use IP analysis to adapt your content." Instead, add a visible language switcher on every page that links to the same page in each other language, not to each language's homepage. If you suggest a language, do it with a dismissible banner, never a forced redirect.

Check: open a Spanish page from a browser set to English. It should stay in Spanish, with a working link to the English version of the same page.

Step 7: validate on every build

Example prompt: Write a check that crawls the built site and reports: pages whose hreflang set doesn't include themselves, pairs that don't link back to each other, relative or http URLs in hreflang, unsupported language or region codes, hreflang targets that don't return 200, pages whose lang attribute doesn't match their hreflang language, and pages with no translation listed in translations.json. Fail the build on any error.

Also check that no language version's canonical tag points at a different language version, which would tell search engines to prefer the other page. Add this check to your QA routine before every deploy, and see Claude Code for technical SEO for the wider audit.

Step 8: keep languages in sync

The hardest part of a multilingual site is month six, when the English pages have changed and the translations haven't. Ask Claude Code to record, for each translated page, which version of the source page it was translated from. When the source changes, the build can list the translations that are now out of date. A person then decides which need updating first. An outdated translation with a wrong price is worse than no translation.

Conclusion

Claude Code takes most of the error-prone engineering out of a multilingual site: separate URLs, hreflang generated from one map, lang attributes, a switcher and build checks that catch broken links between versions. Translations still need fluent human review, and the choice of markets and URL structure is a business decision. If you'd like help building or fixing a multilingual site, see our Claude Code development services. More guides are in our Claude Code Guide.

Frequently asked questions