How do you translate a Hugo website while preserving page relationships, language-specific URLs and the meaning of technical content? Hugo’s multilingual mode offers a structured approach: configure languages, provide translated content, connect equivalent pages and generate links from the pages that actually exist.
If you are searching for Hugo multilingual configuration, defaultContentLanguage, contentDir, about.en.md, about.fr.md, translationKey, AllTranslations, language-specific slugs or missing i18n strings, this guide follows the full build and release process. It explains both the mechanics and the checks that tell you whether an international website is genuinely usable.
Hugo can render language-specific websites and help localize labels, dates and numbers. It cannot guarantee the translated prose is correct. A reliable multilingual Hugo site should show the right language, take visitors to true equivalent pages, avoid claiming translations that do not exist and preserve every consequential fact in the original.
A compact configuration illustration
Hugo supports both filename-based language variants and separate language content directories. This example illustrates the directory approach; verify it against the release installed in your project.
defaultContentLanguage: en
languages:
en:
contentDir: content/en
label: English
locale: en-US
weight: 1
fr:
contentDir: content/fr
label: Français
locale: fr-FR
weight: 2In a filename-based project, content/about.en.md and content/about.fr.md can represent the same page. The selected architecture should be consistent across source content and template links.
1. Understand Hugo’s multilingual publishing model
Hugo builds a static website from source content, layouts, data and project configuration. Multilingual mode produces language-aware pages from that content. The language of a route and the existence of a translated article are related but different facts.
Begin by listing the site’s languages, content directories, layouts and output hostnames. Choose a representative article, an index page and an intentionally untranslated page. These three cases reveal most routing and fallback assumptions.
2. Establish a correct source baseline
Before adding a locale, run the project’s normal build and inspect generated links, page titles and article identities. A language change often exposes previously hidden hardcoded routes; without a baseline, teams may blame translation for unrelated template errors.
Record the Hugo release and important theme or module versions. Verify the build in a clean working directory and note the public URLs that must remain stable after the new language edition is added.
3. Configure defaultContentLanguage
Hugo’s official language configuration documents defaultContentLanguage as the project’s default. When languages are defined, it must correspond to one of the configured language keys. This is the edition presented at the usual default routes.
Choose it according to the editorial source of truth and existing public address structure. Test the home page and an incoming deep link with no locale selected. A default language should not change unpredictably because of a browser cookie.
4. Decide on defaultContentLanguageInSubdir
Hugo documents defaultContentLanguageInSubdir to control whether the default language is published beneath its own locale directory. This determines whether the English edition might live at / or /en/ and affects redirects and canonical URLs.
Before switching the option on a published site, inventory established URLs and backlinks. Test both prefixed and unprefixed routes and decide which should be canonical. An international release must not accidentally strand existing readers.
5. Configure each language intentionally
The current Hugo language configuration includes a languages table or mapping with settings such as label, locale, weight and optionally contentDir. The display label and locale have distinct purposes, and language weights can affect ordering.
Use language identifiers and labels that correspond to real maintained editions. A dropdown containing twenty languages is not valuable if only two have meaningful content. Confirm the selected locale’s typography, formatting and actual article availability.
6. Set up language-specific content directories
Hugo’s documentation offers translation by directory. Each configured language can have its own contentDir, allowing teams to maintain English files beneath one directory and French beneath another.
Choose a consistent path pattern and keep equivalent page relationships discoverable. A separate directory can simplify contributor permissions, but it also makes it easy to duplicate structures without maintaining meaning. Test a pair of translated files with the same content purpose.
7. Use language-suffixed filenames when appropriate
Hugo also supports translation by filename, such as content/about.en.md and content/about.fr.md. Files with a shared path and base name are connected as language variants, and the language code suffix must follow documented conventions.
Try one English and French page pair in staging. Confirm that each generated URL loads the correct body, not just a translated theme. If the file lacks a language code, Hugo assigns it to the default language according to documented behavior.
8. Keep language suffixes in the expected case
Hugo’s multilingual documentation notes that filename language codes must use lowercase forms; for example, about.en-us.md rather than an uppercase region code in the suffix. The file naming convention is part of page discovery.
Create one example for a regional language and inspect the resulting build. A file that appears visually correct in the repository but is not classified as expected can disappear from target-language archives or translation menus.
9. Separate identity from public slugs
A page’s translated headline may be very different from the source title. Hugo can use stable path relationships or a front matter translationKey to connect pages. That relationship is not identical to the URL visitors see.
Give each article a durable editorial identity, then allow the target-language slug to be natural for the reader. Verify both the identity link and the generated page address after changing a translated title.
10. Understand translationKey
Hugo documents the translationKey front matter parameter as an explicit way to associate equivalent pages. When a custom key is absent, a page’s translation identity can be derived from its path. This matters when filenames differ between languages.
Use matching keys only for genuinely equivalent content. Do not connect an introductory article with an advanced tutorial merely because they share a keyword. Check that the key produces the counterpart list expected by the theme.
11. Use AllTranslations correctly
Hugo’s page method AllTranslations returns the current page and its translated variants. It is useful for a language selector that needs to offer every real edition of a specific page.
Inspect the resulting list for a fully translated article and a source-only article. Only actual counterparts should be advertised. A template should not manufacture translations by appending prefixes to a URL that has no target page.
12. Know what Translations excludes
The Translations method returns a page’s other-language counterparts while excluding the current page. This is convenient for a menu listing alternative editions, but the template still needs to show the current language accessibly.
Test a page with one edition, two editions and three editions. A page with no translations should not display empty or misleading choices. Clear absence is more useful than a switcher that silently opens a generic homepage.
13. Build the language switcher from page objects
Language selectors are often created in Hugo templates using properties of actual page objects. These objects know their generated permalinks and translation relationships. Guessing destination URLs with string concatenation can break localized paths.
Use RelPermalink or Permalink values from the correct page objects and check the HTML output. A switcher is complete when it reaches the equivalent page and clearly explains unavailable editions.
14. Distinguish global language navigation from article switching
A general header menu may switch to the homepage of another language edition; an article-level switch should normally keep the reader on equivalent content. The two operations have different meanings.
Label the behavior according to the destination. If a translated article is missing, offer a language home link with that limitation made clear rather than pretending an unrelated homepage is the article’s translation.
15. Localize slugs without breaking counterpart relationships
Hugo supports a translated slug or URL through front matter. A French page may use a-propos while an English page uses about. The pages can remain equivalents when their translation identity is maintained.
Test links from both sides and inspect permanent public addresses. Do not change old slugs merely to make newly translated ones look symmetrical. Redirects should be planned when public URLs actually change.
16. Protect existing permalink structure
Permalink rules and language prefixes interact with routes generated for posts, sections and categories. Introducing localization can expose hardcoded paths in a theme or content links.
Open a deep blog article, a tag page and a section index in each language. Compare production URLs with the intended structure. Correct template link construction before publishing if links accidentally contain duplicate locale segments.
17. Use language-aware URL functions
Hugo’s multilingual guide recommends generating links through built-in page permalinks or language-aware URL functions rather than arbitrary path concatenation. This helps keep navigation valid when default languages and subdirectories differ.
Inspect menus, footers, breadcrumbs and related-content cards for hardcoded root-relative paths. Fix them at their actual template owner and test a nested article in each locale.
18. Distinguish translated content from UI messages
Hugo can localize template strings using its translation facilities, but this does not mean it translates the Markdown body of an article. The two layers require different review and maintenance.
List source-language residue in the header, footer, pagination, error states and forms separately from missing article translations. Choose the right owner for each issue instead of replacing strings throughout the repository.
19. Use language resource keys meaningfully
Navigation terms and short interface messages may be stored in dedicated translation resources. Their keys should describe intent, such as search.no_results, not visual appearance such as blue_button.
Give language reviewers the component context and any variable requirements. Open is ambiguous without context; it may mean expanding a panel or describing business availability. Review the result in a rendered page.
20. Check missing interface messages
Hugo documents a configuration option for missing translation placeholders and a –printI18nWarnings diagnostic flag. These help locate untranslated template strings without pretending that missing values have been written.
Use the diagnostics in a development build and review their results before publishing. Do not leave diagnostic placeholders in production pages unless this is a deliberate internal testing environment.
21. Keep locale-aware dates and numbers faithful
Hugo’s multilingual documentation addresses localization of dates, numbers, currencies, percentages and collation. Such formatting should make data understandable while preserving exact underlying values.
Test an ambiguous date, decimal amount, percentage and sorted list in every target locale. A changed presentation must not turn a factual amount into a different claim or alter a deadline.
22. Treat page bundles and media carefully
Hugo pages may have page resources such as images or downloads. Shared and language-specific resources require an explicit editorial plan, especially when media contain embedded wording.
Check page bundle paths and published media URLs from the target page. Translate important captions and alternative text, supply localized screenshots when accurate and label files that remain in another language.
23. Preserve code and technical references
A software tutorial may include flags, API routes, configuration keys and version identifiers. Those strings need exact handling even while the surrounding explanation becomes natural in another language.
Protect executable fragments, citations, formulas and numerical data. Run a representative example from the target-language edition to make sure punctuation or a translated identifier has not changed the intended operation.
24. Plan real article translation coverage
A project can offer multilingual theme labels while many articles exist only in the default language. A route or language label is not a guarantee of editorial coverage.
Maintain a compact register of article identities, available locales, source revisions and approval states. Use that data to choose what the switcher shows and to avoid advertising unavailable translations.
25. Keep source revisions tied to translations
A translated article can become stale as the source gains a new exception, changed requirement or revised procedure. Grammar remains correct while the meaning becomes out of date.
Track the approved source revision. Prioritize changes that alter deadlines, safety, eligibility or required actions. Compare claims and conditions, not merely paragraph counts or publication timestamps.
26. Check what happens when page content is missing
Hugo’s string-localization fallback is not the same as creating an absent article translation. Template messages may use a default-language value, while content pages follow their own language-aware discovery and relationship rules.
Create an English-only article and open the French site. Inspect whether a counterpart route actually exists. Never advertise a translated page merely because the theme can render a French menu.
27. Understand the optional content-merge approach
Hugo’s multilingual documentation points to lang.Merge for situations involving missing content translations. Merging content is a deliberate template-level choice and should not be mistaken for automatically written target-language text.
Use it only when the intended fallback behavior has been explicitly decided. Test what language the merged page’s excerpts and links use, and label original-language material honestly instead of hiding the fallback.
28. Plan language-specific menus
A language edition needs menu labels that readers recognize, destinations that exist and an active state that follows the page reached. Menu configuration may be language-specific even when the underlying page identity is shared.
Test every primary item in English and French, including a locale with fewer pages. A French label that leads directly to an English article without warning does not provide a coherent browsing experience.
29. Handle translated taxonomies
Tags and categories help readers explore a Hugo site. A translated label does not automatically guarantee that the target language contains an appropriate set of articles for that category.
Decide whether taxonomy names are shared concepts with localized labels or independently maintained classifications. Review category paths, counts and actual result languages before publishing a new edition.
30. Verify section lists and summaries
A section page often combines a title, a collection of articles and short summaries. Those components can come from different content and template sources, so a partially translated section may look deceptively complete.
Open a section with many articles and another with few translations. Check counts, headings, article language, snippets and link destinations. Do not invent a target-language excerpt for a source-only article.
31. Inspect list pagination
Pagination changes the URLs readers navigate and the subset of posts displayed. A language edition with fewer articles may have different page counts and end-of-list behavior.
Test next and previous controls on the first and final archive pages. Confirm they remain within the selected language and never link to a nonexistent page number or another edition’s archive.
32. Use correct localized site titles
Hugo supports language-specific site configuration, including display labels and titles. A site title should tell the reader what publication they have entered rather than simply repeat a copied default-language phrase.
Check the document title, shared header, browser tab and social previews. Do not label an incomplete language edition as fully translated when key content is unavailable.
33. Keep search language-aware
Hugo sites often implement search through client-side indexes or external services rather than one universal built-in search screen. The chosen integration may index languages differently from the site’s page routes.
Test a French word that appears only in French content, a phrase with accents and a query with no results. Inspect both result language and destination path, then translate search feedback owned by the interface.
34. Localize error states and 404 pages
Readers discover language problems on error pages as often as on ordinary articles. A French navigation journey that ends on an English-only 404 screen can leave visitors unable to recover.
Check the error title, explanation, home link and language choice. If a missing translation is intentional, communicate that situation rather than displaying a generic broken-page message.
35. Keep RSS and other feeds coherent
Feed subscribers receive content and URLs outside the main site interface. A feed can expose English excerpts from a French site or link to the wrong language because the feed templates use defaults.
Decide whether feeds are language-specific or explicitly mixed. Inspect their titles, entries, permalinks and content language with an actual feed reader or validator.
36. Check sitemap URLs rather than assumptions
A multilingual build can emit many routes. The sitemap should reflect actual published pages, not fabricated variants derived from a list of configured languages.
Inspect generated sitemap entries and follow a representative set of links. A locale directory with only a homepage should not imply that every deep article has been translated.
37. Build alternate-language metadata from page relationships
Hreflang relationships should connect genuine equivalents. Hugo’s page translation methods can supply real page objects, making them safer than constructing all combinations from language codes.
Open each declared alternate URL and confirm its content identity. Where a page has no target-language counterpart, avoid declaring a fabricated link simply to fill the set.
38. Keep canonical rules consistent
A genuine translation normally deserves an address representing its own edition. An intentional fallback or duplicate needs a different editorial and metadata decision, based on what actually exists.
Inspect canonical tags on pages in each locale, including the default language with and without a prefix. Watch for redirects that create loops or accidentally collapse distinct translations onto one language.
39. Choose single-host or multihost deployment deliberately
Hugo’s documentation supports both single-host and multihost multilingual configurations. Different domains can be useful for regional services, but they bring certificate, redirect and cross-host link responsibilities.
Select an architecture before publishing. Test root and deep URLs for each host, verify canonical addresses and ensure that article-level language switches do not send the reader to unrelated pages.
40. Protect source-language citations
A translated technical article may reference official documentation whose title, version or source URL remains in English. Readers still need to locate and verify the actual source.
Preserve document numbers, software versions and publisher names. Where a translated title is supplied for explanation, retain enough original identifying detail to prevent confusing a different edition or publication.
41. Review images with language-specific text
A Hugo page bundle can contain screenshots, diagrams, charts and downloadable documents. Their embedded words may not change when the surrounding Markdown is translated.
Inventory critical media, produce honest target-language captions and use localized replacements where accurate. Verify that page resource links work in each edition and do not expose a missing asset path.
42. Verify image alternative text
Alternative text is part of the message delivered to readers using assistive technology. It may be stored in page front matter or layout data rather than in the visible article prose.
Check alternative text in each language and avoid merely copying an English description beneath a French article. Preserve the information needed to understand the image’s function, not just a list of objects.
43. Treat dates as data with a locale-aware display
A publication timestamp is an event, not a phrase to be translated freely. Hugo’s localization tools can format it for readers while the underlying moment remains unchanged.
Test an ambiguous date and a time zone-sensitive event. Confirm the same moment is represented in every edition, and use explicit months or zones where readers could otherwise misunderstand the schedule.
44. Handle numeric and currency formatting carefully
Decimal separators, grouping conventions, currencies and percentage formats vary. Localization should make values clear without silently converting a price or changing a threshold.
Use the current locale’s appropriate presentation, label any currency conversion and verify representative values against source data. A changed separator must not turn 1.5 into 15.
45. Preserve plural and variable meaning
Template messages often combine quantities with nouns, such as one result or many results. Their grammar varies by language. Translated strings should be tested using actual numeric arguments, not only static previews.
Check zero, one, two and larger values in every target language. Validate placeholders that represent names, numbers and URLs, and test that they remain intact after translation.
46. Plan right-to-left editions as more than translated text
For Arabic or Hebrew, the direction of prose, punctuation and navigation may differ from English. Mixed-script software commands and financial amounts need additional inspection rather than blanket reversal.
Test a full article with a code block, URL and number. Use appropriate document language and direction and verify keyboard focus order, mobile layout and accessible link names.
47. Improve accessibility across language switches
The language selector should announce its purpose, identify available destinations and work with a keyboard. A locale link must not rely solely on a flag icon or an unexplained two-letter abbreviation.
Test an article that has two translations and one that has none. Check link labels, the current language, page titles and behavior when a user cannot reach the expected counterpart.
48. Allow translated text to expand
Language expansion can break tabs, buttons and cards designed around short English labels. A multilingual site should be robust at mobile widths and enlarged text sizes.
Inspect the longest navigation label and summary in each edition. Allow readable wrapping and avoid shrinking text until it becomes inaccessible merely to keep the original layout.
49. Protect exact software syntax
Code blocks, command flags, API paths and configuration keys are often deliberately in one language or follow fixed syntax. Translating them as ordinary prose can make instructions fail.
Mark protected strings during editorial review and run a representative example from the published target-language page. Translate the explanation while preserving executable tokens and exact numeric requirements.
50. Handle link localization at article depth
Relative links can change meaning when pages move under language prefixes or localized slugs. A path working from the homepage might break within a nested article.
Follow internal links from both top-level and deep pages. Prefer page-aware permalink construction in templates and stable identity mappings for translated counterpart links.
51. Track stale translations and source revisions
A target-language page can remain grammatically good while its source gains a warning, new deadline or revised procedure. The edition is then substantively outdated.
Record the source revision each target edition was approved against. Prioritize changes to obligations, exceptions, figures and software steps. Compare reader actions rather than relying on matching word counts.
52. Keep a concise translation inventory
A useful inventory records source ID, target locale, source revision, translated page route, approval state and reviewer. It separates missing pages from untranslated interface strings.
Use the inventory to decide what is eligible for language switching and indexing. It should be possible to answer which editions are complete without inspecting thousands of files manually.
53. Pilot a small bilingual site
Start with a homepage, one long technical article, a section page and an untranslated control case. Together they exercise the major routing, template and identity assumptions.
Build from clean source, compare generated URLs, open real counterparts and have a fluent reader complete a practical task. Fix the pilot before translating an entire content library.
54. Check build warnings and rendered output together
Hugo’s diagnostics can identify missing interface translations, but a clean build does not prove that meaning, links and article identity are correct. Human review complements automated tests.
Run relevant i18n diagnostics in development, inspect the public-style HTML and compare important instructions in source and target languages. Do not publish debugging placeholders as reader-facing text.
55. Maintain a regression route set
A small fixed set of representative URLs helps detect changes after theme updates or content restructuring. Include home, nested article, categories, missing counterpart and language switch journeys.
Retest routes, canonical metadata, page language, media and key controls after each release. A failure that is easy to reproduce can be repaired without rewriting unrelated content.
56. Plan redirects before moving established pages
Turning an existing single-language site into a multilingual one can change the default language path. Such changes affect bookmarks, search listings, feed subscribers and internal references.
Map old URLs to correct new destinations if a migration is necessary. Test for redirect loops, wrong-language redirects and chains that obscure the final canonical page.
57. Test production deployment independently
Static builds may work locally while hosting rules change path handling, compression or redirects. A generated page file is not sufficient evidence that the public URL serves it.
Open real production-style URLs in a fresh browser and inspect status codes, language metadata and page text. Include alternative hosts if a multihost configuration is used.
58. Review a complete reader journey
The best validation combines comprehension and navigation. A reader should be able to open a relevant article, understand its conditions, switch language if an equivalent exists and continue without unexpected changes in content.
Ask a fluent reader to perform a normal task using only the target edition. Note ambiguity, dead ends and missing context. An accurate site is defined by human success, not the number of languages listed in configuration.
59. Separate editorial and technical sign-off
A developer can check page relationships but fail to recognize a mistranslated conditional. A translator can improve style but miss an invalid config key or an old software version.
Give both reviews meaningful responsibilities. Record which source revision was approved and which live URL was tested, then revisit high-risk content when the source changes.
60. Define a durable completion standard
An international Hugo site is not complete because every URL contains a language code. It is reliable when actual approved content, truthful metadata, functional navigation and clear missing-translation behavior agree.
Monitor coverage, stale pages, broken counterpart links and reported comprehension problems. The editorial outcome is a website readers can use across languages without losing the intended meaning.
Three practical publishing cases
Case study: a bilingual software documentation library
An open-source software team maintains a Hugo site in English and French. It has configured two languages, but one tutorial uses a localized French slug and is no longer paired with its English counterpart because their paths differ. The header language menu links to French home rather than the matching article. The reader loses their context during a technical task.
The team gives both pages a deliberate shared translationKey, confirms the generated counterpart relationship and builds the switcher from real page objects. It also checks commands and version requirements in the translation. A language selector that reaches the correct destination but describes an old software release would still be defective.
Finally, a French-speaking tester follows the tutorial, executes a representative safe command and returns to the section index. The tester verifies actual comprehension while the developer checks routing and metadata. Both outcomes are required before the new edition is advertised.
Case study: localized pages that were never translated
A nonprofit adds French language configuration to a Hugo information website. Its layout text is translated, but most Markdown pages are English-only. Editors create language-related navigation links from locale codes and inadvertently advertise French counterparts that do not exist. Visitors encounter empty routes or unrelated language home pages.
The publisher first inventories genuine translations and removes fabricated page-level alternatives. It labels the general French home link appropriately and creates a clear editorial queue for missing articles. Missing interface strings are tracked separately from missing article content, because those problems require different fixes.
Once a French guide is approved, the team creates the actual target file, tests the page relationship and checks the meaning of important conditions. It updates the alternate-language metadata only for published equivalents. The release can be smaller and still be truthful.
Case study: an international guide with regional data
A global resource site uses Hugo’s locale-aware formatting for dates and numbers. An article describes an application deadline, a currency amount and several technical restrictions. Local editors want the content to feel natural to readers in another region.
Formatting can improve clarity, but facts must stay traceable. A currency conversion needs a named basis and date; a deadline must retain its real time zone; a changed date order must not produce a different calendar day. The local version should communicate the same requirement even where grammar and examples change.
The reviewers compare source and target claims, then inspect the public page’s summary, structured metadata and links. A fluent reader explains the action they would take. This prevents presentation preferences from silently changing the publication’s actual advice.
Frequently asked questions
Does Hugo translate Markdown content automatically?
No. Hugo connects and builds language-specific source files; translated prose must be provided and reviewed. Template string localization is a separate feature.
How are two pages recognized as translations?
Hugo documents matching filename paths, per-language content directories and explicit translationKey values for associating page counterparts.
What is the difference between Translations and AllTranslations?
Translations lists other-language counterparts, excluding the current page. AllTranslations includes the current page as well.
Can French pages have different slugs?
Yes. Hugo supports localized front matter slugs or URLs while a page relationship can remain linked through its translation identity.
What happens when a string translation is missing?
Hugo can use the default-language value for a missing interface string, or an empty string if there is no default. Development diagnostics help find gaps.
Should I invent a /fr/ counterpart for an English-only page?
No. Offer an honest alternative destination and declare alternate-language metadata only for genuine equivalent pages.
How do I validate production readiness?
Check source revision, generated links, HTML language, canonical and alternate relationships, numbers, code, accessibility and a real target-language task.
Official Hugo documentation and connected reading
The Hugo multilingual mode guide explains translated content, localizing output and missing interface strings. The language configuration reference explains the default language and locale options. For page pairing, consult the official TranslationKey, Translations and AllTranslations references. Broader meaning-preservation principles appear in Master Art of Translation; other platform guides are indexed in the Translate Like a Pro series. This chapter concentrates on Hugo’s page relationships, locale URLs, templates and publishing quality.