Configure English fallback for untranslated Japanese content

Lauren Barkerrequested to merge
gitlab-com/localization/tech-docs-forked-projects/prod/gitlab-docs:english-fallback-with-content into main

What does this MR do and why?

This MR improves the user experience for Japanese documentation visitors by configuring Hugo to serve English content when Japanese translations are not available, preventing 404 errors for untranslated pages.

Changes made:

Updated hugo.yaml configuration:

  • Added cascade fallback configuration for ja-jp language
  • Modified module mounts to include English content as fallback for Japanese routes
  • Duplicated mount sources so both Japanese and English content are available for each target path
  • Updated canonical-url.html detects when a non-English page is showing English content as fallback, then replaces the canonical url with the English URL. If it is not a fallback, it displays the Japanese URL as the canonical url.

Expected behavior:

  • Visit /ja-jp/translated-page/ → Shows Japanese content
  • Visit /ja-jp/untranslated-page/ → Shows English content instead of 404
  • Maintains proper language context and navigation while providing fallback content

Why this matters:

Japanese users will now see the source English documentation when translations don't exist, rather than encountering broken links or 404 errors. This ensures continuous access to all GitLab documentation while translations are being developed.

Expected results:

  • Japanese translated pages continue to display correctly - example - /ja-jp/tutorials/
  • Untranslated Japanese URLs now serve English content - example - /ja-jp/user/get_started/
  • No 404 errors for missing Japanese translations
  • Navigation and site structure remain intact

Closes gitlab-com/localization/docs-site-localization#200 (closed)

Screenshots, screen recordings, or links to review app

Screen_Recording_2025-06-11_at_3.38.43_PM

How to set up and validate locally

  1. Configure a local GitLab Docs environment.
  2. Check out this branch.
  3. Enable japanese site, languages.ja-jp.disabled: false
  4. make view
  5. Browse the site, in English and Japanese. Untranslated content will display in english on /ja-jp/ routes.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Lauren Barker

Merge request reports