How to automatically fallback to the default language when a requested page doesn't have a translation?

[huanlin]

Hi, my website contains multiple products' documents in sub-folders, and some of them have localized versions (e.g. Chinese), some don't.
How to automatically fallback to the default language (English) when a requested page doesn't have a translation?
After reading Docsy's code (as below), I still don't know how to do it.

{{/* Link directly to documentation etc., if possible. */ -}}
{{ $langPage := cond (gt (len .Translations) 0) . .Site.Home -}}
<div class="dropdown">
  <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    {{- $langPage.Language.LanguageName -}}
  </a>
  <ul class="dropdown-menu">
    {{ range $langPage.Translations -}}
    <li><a class="dropdown-item" href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
    {{ end -}}
  </ul>
</div>

Any suggestions?

Related discussions:

• Possitle solution: Do all page bundles need localized copies once you add a new language?
• Question: multilingual site fallback to default language if content is not translated

The following Hugo methods are just for reference and collecting ideas:

• Page.Language
• Page.AllTranslations
• Page.Translations
• site.Languages

[chalin]

Hi. I'm experimenting with (and hence cannot fully yet endorse this approach) the use of mount points to specify fallback pages. This is effectively the mount solution proposed by @jmooring in Do all page bundles need localized copies once you add a new language?, that you pointed out.

This approach comes at a cost: it effectively duplicates pages, which is a problem for SEO ... unless we set the canonical link properly. I'm working on fixing the canonical link, you can track progress via open-telemetry/opentelemetry.io#4487. I'll see if I can port a variant of that solution to Docsy (#1537) when I've vetted it enough.

@jmooring: are you aware if there are other fixes elsewhere for this canonical link issue of fallback pages?

Here's how I set it up for the OTel website:

module:
  mounts:
    - source: content/en
      target: content
    - source: content/zh
      target: content
      lang: zh
    - excludeFiles: specs/*
      source: content/en/docs # zh missing-page fallback
      target: content/docs
      lang: zh

This is excerpt from https://github.com/open-telemetry/opentelemetry.io/blob/269c3b343926615bfc78a237562a4d28d1a528d3/hugo.yaml#L212-L222.

You can see this live at, for example: https://opentelemetry.io/zh/docs/.

[huanlin]

I applied the mounts configurations to my website and it seems working perfectly.
My configuration: https://github.com/huanlin/huanlin.github.io/blob/3074f93f6cb23fa1ae10405e811657b213774e4e/hugo.toml#L266-L283

In addition, I commented out all contentDir settings in my hugo.toml according to the official document:

if you add a mounts section you should remove the old contentDir, staticDir, etc. settings.

Thank you @chalin and @jmooring ! You guys saved my day.

[jmooring]

@chalin

are you aware if there are other fixes elsewhere for this canonical link issue of fallback pages?

layouts/partials/link-element-rel-canonical.html

{{- /*
Renders a link element with the canonical URL for the page.

This is designed to work with multilingual content module mounts that fill in
missing translations as described in https://discourse.gohugo.io/t/37225.

Assumptions:

1. Missing translations always fall back to the default language. This won't
   work with a waterfall fall back setup.

2. This assumes translation by directory, not by language key in file name.

3. This assumes contentDir is single segment or a single segment followed by
   the language key. For example:

    contentDir = 'content'
    contentDir = 'content/en'

    These will fail:

    contentDir = 'content/foo'
    contentDir = 'content/foo/en'

@param {page} . The current page
@returns {template.HTML}

@example: {{ partial "link-element-rel-canonical" . }}
*/}}

{{- $canonicalURL := .Permalink }}
{{- with .File }}
  {{- $filename := strings.TrimPrefix hugo.WorkingDir .Filename }}

  {{- $slashSplit := split $filename "/" }}       {{/* Linux and macOS */}}
  {{- $backSlashSplit := split $filename "\\" }}  {{/* Windows */}}

  {{- $slashLang := index $slashSplit 2 }}
  {{- $backSlashLang := index $backSlashSplit 2 }}

  {{- if not (in (slice $slashLang $backSlashLang) $.Language.Lang) }}
    {{- $canonicalURL = (index $.AllTranslations 0).Permalink }}
  {{- end }}
{{- end }}
<link rel="canonical" href="{{ $canonicalURL }}">

This partial has some caveats (see comments in header), but it seems to work OK on both Linux and Windows.

You can take it for a spin by cloning this again:

git clone --single-branch -b hugo-forum-topic-37225 https://github.com/jmooring/hugo-testing hugo-forum-topic-37225
cd hugo-forum-topic-37225
hugo server

With the Hugo methods currently available, this seems a bit fragile, but I'll let you be the judge.

[chalin]

Oh, very nice, thank you @jmooring. You'll find below what I had come up with, which you can see via PR #4494/files. Hmm, I'll have to study your solution more carefully to see if I also need to do something special to cater to Windows environments.

opentelemetry.io/layouts/partials/hooks/head-end.html

{{ with .Params.canonical_url -}}

<link rel="canonical" href="{{ . }}">

{{- else -}}

  {{ $canonicalURL := .Permalink -}}

  {{ $defaultLang := "en" -}}
  {{ if and (ne .Language.Lang $defaultLang) .File -}}
    {{/* This page is in a non-default-language section */ -}}
    {{ $pagePath := strings.TrimPrefix (add hugo.WorkingDir "/content/") .File.Filename -}}
    {{ if hasPrefix $pagePath $defaultLang -}}

      {{/* This page is actually a default-language fallback page. Use the link
      to the origin of the fallback page as canonical reference. */ -}}

      {{ $translationPages := where .Translations "Lang" $defaultLang -}}
      {{ $translation := index $translationPages 0 -}}
      {{ with $translation -}}
        {{ $canonicalURL = .Permalink -}}
      {{ end -}}
    {{ end -}}
  {{ end -}}
  <link rel="canonical" href="{{ $canonicalURL }}">

{{- end -}}

In which order are elements of AllTranslations sorted? I seem to recall reading somewhere in the Hugo docs that the first element was always the page from the defaultContentLanguage, but I'm not seeing that mention in the AllTranslations page.

[jmooring]

Regardless of approach, .File.Filename is the key to success. It's the only way you can get to the language of the file rather than the language of the page. In my approach I wanted to avoid hardcoding the "content" directory or the the default language.

[chalin]

Oh right, I hadn't thought about that as hardcoding the content directory. Very good point.

If I end up using your code, would you like it attributed, if so how? Thank you again for your feedback, it is much appreciated 🙏.

[jmooring]

would you like it attributed

No, but thanks for asking.

[huanlin]

Just to add one note here.
Today I saw a "side effect" (if you will) of this approach, that is when I use the Search box, each item in the search result is doubled.