Multilingual HubSpot Site: One Theme for Many Languages, Without the Headache

Every company that sells in more than one country reaches the same crossroads: how to have the site in several languages without it becoming a maintenance nightmare? The naive solution, keeping three separate sites, one per language, multiplies the work by three and guarantees that, sooner or later, they will fall out of sync, with one version updated and the others forgotten.

On HubSpot Content Hub, there is a much better path: a single theme that serves all languages. In this guide, I will show how to structure that, separating the interface text into translation files, connecting the page variations by language, configuring language switching and hreflang, and taking care of international SEO. The result is a multilingual site that stays coherent without tripling the effort.

One theme, many languages

The central principle is not to duplicate the theme per language. You keep a single theme, with all the structure, styles, and modules shared, and separate only what actually changes between languages: the text. The visual elements, the behavior, and the layout are the same for all languages, because the structure is single.

The big advantage shows up in maintenance. When you change a color, adjust a module, or fix a behavior, the change applies to all languages at once, because they all share the same base. There is no risk of the Portuguese site evolving and the English site falling behind, because, at heart, they are the same site speaking different languages. That structural unity is what makes the multilingual setup sustainable.

Translation files for the interface

The interface's fixed text, and not the pages' editorial content, lives in field translation files. In HubSpot, each module folder and each theme folder can carry a _locales folder, with a subfolder per language locale and a messages.json inside it holding the translations. We are talking about button labels, menu items, system messages, everything that repeats and needs to appear in the right language. The template references a key, and HubSpot serves the translated text according to the page's language.

That pattern avoids the worst multilingual mistake: text hardcoded straight into the code in a single language. When the interface texts live in organized translation files, adding a new language becomes a matter of translating the keys, not rewriting templates. And fixing a translation means editing one place, not hunting the word scattered across dozens of modules. The organization of translations is what keeps growth to new languages simple. Module field translations can also be set in the Design Manager, while theme field translations have no interface there and are edited directly in the .json files.

Page variations by language

While the interface text lives in the translation files, the editorial content, the articles, the product pages, the sales copy, uses HubSpot's language variations feature. You have a primary page and its translations, linked to each other as the same content in different languages. HubSpot understands that relationship as a group of variations.

That connection between variations is more than internal organization. It is what lets HubSpot route the visitor to the right version and what supports international SEO, because search engines need to understand that those pages are the same thing in different languages, not duplicate content. Treating translations as linked variations, and not as loose pages, is what makes the multilingual setup work for both the user and the search engines.

Language switching and the hreflang tag

The site's language switcher should be smart: when switching language, it takes the visitor to the equivalent version of the page they are on, and does not dump everyone back on the home page. Good news: HubSpot already rewrites the links on translated pages to point to the same-language version, so visitors stay in their language without you wiring that by hand, and you can opt a specific element out with the hs-skip-lang-url-rewrite class. What HubSpot does not add for you is the switcher control itself: it is a module you place in the theme, and there is a ready example in the CMS boilerplate to start from. Someone reading an article in Portuguese who clicks English expects the same article in English, not the landing page. That care preserves the visitor's context and patience.

On the search engine side, the key piece is the hreflang tag, and the good news is that HubSpot generates it for you automatically across the multi-language content group, using the right language code. It declares, on each page, which version serves each language and region, telling Google which to deliver to whom, so the search engine does not show the wrong version to the wrong visitor, like the Spanish page to someone in Brazil. Because HubSpot also adds each variation to the XML sitemap and marks the alternates, your job is less about writing these tags and more about keeping the variations properly linked, so the automation has the right relationships to describe. One caveat for developers: HubSpot declares the page language in the head automatically for drag-and-drop templates, but on coded templates you set it yourself, populating the lang attribute via HubL.

International SEO best practices

A well-built multilingual site follows a set of best practices that, together, ensure each version is found and ranks well in its region. They are few and direct, but they make all the difference in the international result.

• Clear per-language URLs, with a consistent prefix or subdomain that signals the language.
• The hreflang tag on every version, each pointing to the others, closing the loop.
• Real translations, done or reviewed by people, not unreviewed machine output, so the content does not sound artificial.
• A language switcher that preserves the current page, changing only the language, and never dumps the visitor on the home page.

Why this matters for your operation

For a company that sells in several markets, the multilingual site is the gateway to each of them. A site that speaks each region's language well, with quality translation and the right version delivered to each visitor, conveys respect for the local market and converts far more than a single English version for everyone. A well-built multilingual structure is what makes international expansion truly viable in digital.

And doing it with a single theme, instead of separate sites, is what makes the operation sustainable. The team maintains one site, not three, and each improvement applies to all markets at once. The difference between a well-designed multilingual structure and an improvised one is the difference between scaling to new countries with ease and drowning the team in maintenance with each added language.

In practice: the three sites that lived out of sync

A company operating in three countries kept three separate sites, one per language, each with its own structure. Every change had to be made three times, and in practice it almost never was: one version got the update and the others fell behind. Over time, the three sites had different looks, mismatched content, and distinct update levels, conveying disorganization.

Consolidating into a single multilingual theme, with translation files for the interface and linked page variations for the content, solved the root of the problem. There came to be one site, in three languages, always in sync. A change applied to all markets at the same time, and the maintenance effort dropped to a third. What was a tripled burden became a single, coherent operation.

Multilingual site checklist

1. Is there a single theme serving all languages, instead of separate sites?
2. Does the interface text live in translation files, one per language?
3. Does the editorial content use language variations linked to each other?
4. Does the language switcher go to the equivalent version of the current page, not the home?
5. Is the hreflang tag on every version, pointing to one another?
6. Are the translations real and reviewed, not unreviewed machine output?

Frequently asked questions

Do I need one theme per language?

No. The ideal is a single theme serving all languages, with the interface text in translation files. That keeps maintenance unified and the structure always consistent across languages.

How does Google know which version to show?

Through the hreflang tag, which HubSpot adds automatically across the multi-language group, declaring the language and region of each version. You do not write it by hand; you keep the page variations linked so HubSpot can generate it correctly.

Should the language switcher go to the home page?

No. It should go to the equivalent version of the current page in another language, preserving context. Someone reading an article who switches language expects the same article, not the landing page.

Where does the translated interface text live?

In field translation files: a _locales folder inside each module or theme folder, with a messages.json per language locale, holding the button labels, menu items, and messages. The template references a key and HubSpot serves the text in the page's language.

Can I use machine translation on the site?

You can, but always review it. Unreviewed machine translation sounds artificial, undermines brand trust, and can hurt ranking. It is better to translate far fewer pages than to translate everything robotically.

How does HubSpot handle pages in multiple languages?

Through the language variations feature: a primary page and its translations linked as the same content in different languages. That relationship helps with visitor routing and international SEO.

Selling in more than one country and want a sustainable multilingual site on HubSpot? At Insight Sales we build multilingual themes with international SEO and quality translation. Talk to our team and find out how we can help.