i18n Routing and Auto Entry Pages

Tralume lets Hugo generate every formal content URL normally, then adds the “smart language entry pages” as a post-build step.

Routing modes

• defaultContentLanguageInSubdir = true: formal content URLs stay under /en-us/... and /zh-hans/..., while neutral entry pages use / and /posts/test/.
• defaultContentLanguageInSubdir = false: the default language keeps the root URL, while neutral entry pages move to /auto/ and /auto/posts/test/.
• Explicit language URLs are never rewritten automatically; only the entry pages perform language-based redirects.
• If a post or page exists in only one language, the entry page redirects straight to that single target without checking localStorage or navigator.languages.

Basic configuration

Set this in hugo.toml:

defaultContentLanguage = 'en-US'
defaultContentLanguageInSubdir = true
# Note: Disable Hugo's built-in default-language redirect and let the theme's entry-page script handle it.
disableDefaultLanguageRedirect = true

[params.i18nRouting]
  # Note: Enable smart language entry pages generated after the build.
  enableAutoEntry = true

Only enable this after you have actually wired python3 tools/gen_auto_entries.py into your real build pipeline. Otherwise, leave it disabled and keep Hugo’s built-in default-language redirect.

Build flow

The theme first asks Hugo to render the formal pages and route-manifest.json, then runs the Python generator:

# Note: First build Hugo's formal content pages and route manifest.
# Note: This example writes verification output to public_test/ to avoid polluting the default public/ directory.
hugo --destination public_test/hugo-auto-entry

# Note: Read route-manifest.json and generate smart entry pages inside the publish directory.
# Note: The script checks for path conflicts and removes stale entry pages generated by previous runs.
python3 tools/gen_auto_entries.py --publish-dir public_test/hugo-auto-entry

Notes

• Entry pages read the fixed localStorage['tralume-language'] key first.
• If no stored language is available, they fall back to navigator.languages.
• If nothing matches, they redirect to the default-language formal page.
• Entry pages always use noindex,follow and point canonical to the formal content page; they do not enter Hugo’s sitemap or RSS outputs.
• If the feature is not enabled, the theme keeps Hugo’s native behavior and lets Hugo handle the root-path default-language redirect.