# Guidance on translations

**URL:** <https://discourse.gohugo.io/t/guidance-on-translations/36627>\
**Category:** support\
**Created:** [January 18, 2022, 9:15am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627 "2022-01-18T09:15:04Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 18, 2022, 9:15am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/1 "2022-01-18T09:15:04Z")

</div>

Hi,  
I’ve been starting to use translations, I get the list of translations for articles, but as I don’t have all the articles translated, when clicking on an article, let’s say in Spanish, and try to link to an article that it’s in English via `{{<ref "xxxx.md">}}` it will complain… however if I force `{{<ref path="xxx.md" lang="en">}}` it will work.

It’s painful but there’s that workaround, but the other issue is related to other pages like ‘search’, static pages,etc…

I would expect Hugo to GET the default translation (English) when there’s no alternate one in the language being used…

Is that possible or it’s a bug/request for enhancement to address?

Thanks in advance

---

<div class="post-metadata">

**Author:** ![davidsneighbour](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/davidsneighbour/32/24507_2.png) [@davidsneighbour](https://discourse.gohugo.io/u/davidsneighbour)\
**Post date:** [January 18, 2022, 11:08am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/2 "2022-01-18T11:08:11Z")

</div>

Hugo does, what your template tells it to do. So if the layout files have a routine in them to get the default translation then that will happen. You will have to post your repo or layout files here for somebody to dig through that.

On your “dot” you have all translations of the current page available, so what you do with it is something like the following in the shortcode:

```auto
{{ $translations := index .Translations "en" }}
{{ range .Translations }}
  {{ if eq .Lang "it" }}
    {{ $translation = . }}
  {{ end }}
{{ end }}

```

After that, if there is an Italian translation available then `$translation.Permalink` will link to it, if not, then it will link to the English version. Add some shortcode options or configuration parameters instead of en and it to make it more dynamic.

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 18, 2022, 11:58am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/3 "2022-01-18T11:58:15Z")

</div>

Thanks David  
I’m using [GitHub - adityatelange/hugo-PaperMod: A fast, clean, responsive Hugo theme.](https://github.com/adityatelange/hugo-PaperMod) as the theme and the translations loop is:

```auto
{{- if .IsTranslated -}}
{{- if (ne .Layout "search") }}
{{- if or .Params.author $.Site.Params.author (.Param "ShowReadingTime") (not .Date.IsZero) }}&nbsp;|&nbsp;{{- end -}}
{{- end }}
<ul class="i18n_list">
    {{- i18n "translations" | default "Translations" }}:
    {{- range .Translations }}
    <li>
        <a href="{{ .Permalink }}">
            {{- if (and $.Site.Params.displayFullLangName (.Language.LanguageName)) }}
            {{- .Language.LanguageName | emojify -}}
            {{- else }}
            {{- .Lang | title -}}
            {{- end -}}
        </a>
    </li>
    {{- end }}
</ul>
{{- end -}}

```

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 18, 2022, 12:51pm UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/4 "2022-01-18T12:51:28Z")

</div>

I was wondering that this, will list the translations for an article, but still not cover the issue I had…  
from an article in English, if I want to link to an article in Spanish or French, etc I would put something like:

{{\<ref “article.md”\>}} and this will fail, as that article doesn’t exist in the language of the source document (english), but only exists as another language.

I’m updating my question as I saw that it’s missing some of the codes there

---

<div class="post-metadata">

**Author:** ![davidsneighbour](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/davidsneighbour/32/24507_2.png) [@davidsneighbour](https://discourse.gohugo.io/u/davidsneighbour)\
**Post date:** [January 19, 2022, 5:53am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/5 "2022-01-19T05:53:29Z")

</div>

If you search long enough you find the solution 😉 Much of it is very hidden in the docs. `relref` has a language parameter. I never tested it, but I think this might help:

> **[Links and Cross References](https://gohugo.io/content-management/cross-references/#link-to-another-language-version)**
>
> Shortcodes for creating links to documents.

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 19, 2022, 7:40am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/6 "2022-01-19T07:40:52Z")

</div>

Thanks, that’s the one I stated I was using… the problem is that I would make use of it, when I specifically want to link to one article in one specific language… but when I link to an article, via the “md file”, I would expect the link to get me any language of the article if the same as the origin one is not there, or doesn’t exist (which is my case when linking from a Spanish article to an English one and there’s no Spanish translation)

---

<div class="post-metadata">

**Author:** ![davidsneighbour](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/davidsneighbour/32/24507_2.png) [@davidsneighbour](https://discourse.gohugo.io/u/davidsneighbour)\
**Post date:** [January 19, 2022, 8:41am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/7 "2022-01-19T08:41:33Z")

</div>

Ok, so slowly we arrive somewhere 🙂

- You are in a Spanish post
- you link to another Spanish post
- that post does not exist, so you expect a link to english

right? In that case English is the sites main language, you have the following somewhere in your config:

```auto
[languages]
  [languages.en]
    title = 'My blog'
    weight = 1

```

If your English is en-us or anything else, keep that on notes.

I don’t see any way to get the `defaultContentLanguage` from the root section of your config, so we go a “hard-coded” way for now.

**NOTE** : this is hobbled together and untested, so don’t give up immediately if it does not work. MIght have typoes.

call this `layouts/shortcodes/langref.html` for now

```auto
{{- $reference := .Get "reference" -}}
{{- $defaultlanguage := "en" -}}{{- /* <-- put your fallback language code here */ -}}
{{- $language := .Get "language" | default $defaultlanguage -}}
{{- $context := $ -}}{{- /* <-- I could be wrong with this one, but inside of the shortcode it should be the current page */ -}}
{{- with site.GetPage $reference }}{{- /* loading the referenced page */ -}}
  {{- if .IsTranslated }}{{- /* checking if the page has translations */ -}}
    {{- with index .Translation $language }}{{- /* translation is available, so let's do this */ -}}
      {{- ref $context (dict "path" $reference "lang" $language) -}}
    {{- else -}}
      {{- ref $context (dict "path" $reference "lang" $defaultlanguage) -}}
    {{- end -}}
  {{- else -}}{{- /* no translations, so let's print out what ref would do at this point */ -}}
    {{- ref $context $reference -}}
  {{- end -}}
{{- else -}}{{- /* referenced page is not available, so let's print out what ref would do at this point */ -}}
  {{- ref $context $reference -}}
{{- end -}}

```

Then call it with `{{< langref reference="/about.md" lang="es" >}}`.

What it should do:

- check if “/about.md” exists or go into “blind” ref creation (as if you called {{\< ref “about.md”\>}})
- check if about.md is translated or return the default reference
- check if language exist and either return that or the default language

Keep an eye on your template tags, those `-` everywhere will result in the shortcode returning only your HTML in the end, not plenty of empty new lines.

Also, not 100% sure if that returns a formatted link or just an URL, you might need to add some HTML at the end.

Edit: I fixed some obvious errors in the shortcode. Still not sure if it works, I have no language site.

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 19, 2022, 8:56am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/8 "2022-01-19T08:56:23Z")

</div>

> [@davidsneighbour](#):
>
> defaultContentLanguage

I’ll check it, the idea of using a custom shortcode for the checks is something I didn’t had in mind, but it’s a clever one, thanks a lot!

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 19, 2022, 5:26pm UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/9 "2022-01-19T17:26:21Z")

</div>

I’m working on something along the lines:

```auto
{{- $reference := .Get 0 -}}
{{- $.Site.Params.languages }}

{{- $context := $ -}}{{- /* <-- I could be wrong with this one, but inside of the shortcode it should be the current page */ -}}

{{- if site.GetPage $reference }}{{- /* loading the referenced page */ -}}
{{ $reference }}

{{- else -}}{{- /* referenced page is not available, so let's print out what ref would do at this point */ -}}

{{- range $.Site.Params.languages -}}
{{- ref $context (dict "path" $reference "lang" "{{ . }}") -}}

{{ end }}

{{- /* site.GetPage $reference */ -}}
{{- end -}}

```

Of course it doesn’t work but I want it for ‘art’ (my shortcode) to use the first (and unique) argument to find reference in same language as linking article, and if not, iterate over the site languages to find the first available.

Is not working but I think that this might work fine

Any hint welcome 🙂  
Thanks!

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [January 19, 2022, 9:12pm UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/10 "2022-01-19T21:12:39Z")

</div>

site config

```auto
[languages.en]
weight = 1
contentDir = 'content/en'
[languages.es]
weight = 2
contentDir = 'content/es'
[languages.de]
weight = 3
contentDir = 'content/de'

```

layouts/shortcodes/relref.html

```auto
{{- with $path := .Get 0 -}}
  {{- $link := "" -}}
  {{- with site.GetPage $path -}}
    {{- $link = .RelPermalink -}}
  {{- else -}}
    {{- range where site.Sites "LanguagePrefix" "ne" site.LanguagePrefix -}}
      {{- if not $link -}}
        {{- with .GetPage $path -}}
          {{- $link = .RelPermalink -}}
        {{- end -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
  {{- with $link -}}
    {{ . }}
  {{- else -}}
    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $path $.Position -}}
  {{- end -}}
{{- else -}}
  {{- errorf "The %q shortcode requires a positional parameter. See %s" .Name .Position -}}
{{- end -}}

```

This looks for the page in the current site (language). If it doesn’t find a match, it ranges through the other sites (languages) ordered by the weight in the `[language]` table. And it works fine for single language sites as well.

---

<div class="post-metadata">

**Author:** ![iranzo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iranzo/32/13339_2.png) [@iranzo](https://discourse.gohugo.io/u/iranzo)\
**Post date:** [January 20, 2022, 8:14am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/11 "2022-01-20T08:14:33Z")

</div>

The above code was also giving me issues, but I finally got into this… that seems to work:

```auto
{{- /* Get path of the article requested */ -}}
{{- $path := .Get 0 -}}

{{- if site.GetPage $path }}
    {{ $path }} {{- /* Article exists, link it */ -}}
{{- else -}}
    {{- /* Article doesn't exist, loop over languages */ -}}
    
    {{- /* Get total languages supported */ -}}
    {{- $totlang := len .Site.Languages -}}

    {{- /* Iterate over them */ -}}
    {{ range $index, $num := (seq $totlang) }}
        {{ if (index site.Sites $index ).GetPage $path }}
            {{- /* Article in language is valid */ -}}
            {{- with (index site.Sites $index ).GetPage $path -}}
                {{- /* Return path to article */ -}}
                {{ .Permalink | relURL}}

                {{- /* Alter index so that we're finished */ -}}
                {{ $index := $totlang}}
            {{end}}
        {{ end }}
    {{ end }}
{{ end }}

```

---

<div class="post-metadata">

**Author:** ![system](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/system/32/1_2.png) [@system](https://discourse.gohugo.io/u/system)\
**Post date:** [April 1, 2022, 8:07am UTC](https://discourse.gohugo.io/t/guidance-on-translations/36627/12 "2022-04-01T08:07:16Z")

</div>

Closed on April 1, 2022, 8:07am UTC

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.