Use localization friendly links in English main site.

[tengqm]

This is a Feature Request

What would you like to be added

The intra-site links in the English documents are currently plain markdown links, as shown below:

* Learn about [Controllers](/docs/concepts/architecture/controller/)

When pages containing such links are translated into another language, the localization team has to take extra care to handle them or else the links will be missing or pointing to an incorrect location. For example, in the Chinese localization, the above line has to be revised to something like:

* 进一步了解 [控制器](/zh/docs/concepts/architecture/controller/)

We need to revise this links to one of the following formats so that the links can be automatically converted to the correct target:

* Learn about [Controllers]({{< relref "docs/concepts/architecture/controller.md" >}})
* Learn about [Controllers]({{< ref "/docs/concepts/architecture/controller.md" >}})

For English main site and all localization sites, the above links can be correctly converted.

Why is this needed

Taking care of so many links for so many localization, across so many teams is error-prone and boring. Once we have the links on the English main site refactored. All localization teams can simply skip updating the link target.

As a bonus, if a link target doesn't exist in a particular language, Hugo can detect the missing link and report errors during build. So we can detect missing links as early as possible.

Comments

For related experiments, see #18374

[sftim]

💯 this

To be honest, when I started contributing I saw that there were localizations and I assumed that a mechanism similar to this already existed. I was genuinely surprised when I realized that localization teams needed to manually track this kind of detail.

[sftim]

/kind feature
Does /priority important-longterm feel right?

[tengqm]

No objections wrt priority. :)

[sftim]

/priority important-longterm

[kbhawkey]

This is interesting!
Looking at the Hugo docs,
https://gohugo.io/content-management/cross-references/

How does this workk?

{{< relref path="document.md" lang="ja" >}}

[tengqm]

Right, if you explicitly provide a lang param, hugo will try redirect you to the specified localization. One use case, in k8s/website could be that for some content, we want to redirect all anchors to the same language, say English.

[tanjunchen]

@tengqm
Is it appropriate to add /zh directly in front of it right now?
/cc @yuxiaobo96
thanks your job!

[tanjunchen]

@sftim @tengqm
Is there any progress on this matter?

[yuxiaobo96]

I think the modification proposed by tengqm is better.

[tengqm]

@tanjunchen No progress yet. If the proposed approach makes sense, we may need to revise the English site as early as possible.

[tanjunchen]

@tanjunchen No progress yet. If the proposed approach makes sense, we may need to revise the English site as early as possible.

done

[Colstuwjx]

Inspired by @tengqm PR #18374 experiment, I have been proposed another PR #18678 for solving this issue.

For ref and relref, I did some research, see hugo 2637, there is no builtin function do check existence ONLY, and I found lang.Merge, but it seems not addressing this issue, see hugo 5612.

For these reasons, I think customized shortcode should be better, and PR #18678 is my answer.
Many thanks to @tengqm great job.

[sftim]

Sort of related: PR #18871.

[remyleone]

@feloy @rekcah78

[tanjunchen]

How about this issue now ? see #18929
They add ja in front of the path.
Is it currently possible to implement similar functionality directly by modifying the hugo code.
/cc @tengqm
/cc @Colstuwjx

[tengqm]

@tanjunchen It is not gonna be a trivial change. I'm not a big fan of adding/modifying hugo code in this repo.

[Colstuwjx]

@tengqm Do you have any idea about solving this issue?

I think it should be a common issue for multilingual site, and we may need to make a conclusion about how to fix this issue at first, and then try to propose a PR for fixing it, here are some considerations in my mind:

We already have multilingual configurations, such as supported languages and their weight, content dir, language alternatives etc, if we could add something for configuring this link convert, for example like adding configuration makeRefAddLangPrefixByDefault=true.

If it's been set true, we could make hugo adding the language prefix by current dir language and its alternative language, therefore, we didn't need to handle this job by manually anymore...

If someone didn't prepare the translation placeholder for the ref, hugo should try to make the ref link fallback to the alternative language, and if it still fails, hugo should panic and throw errors, just like the shortcode ref and relref did.

What do you think about this solution? Or it's welcome if you have another better and workable solution. If we could make a conclusion, and it needs do some job with hugo upstream, I'm ready to do this.

Thanks.

[tengqm]

The makeRefAddLangPrefixByDefault=true suggestion sounds good at fist glance. However, from Hugo developer's perspective, it may not be a priority since there are already existing facility to achieve the same goal. We may even conclude that our current way of codifying intra-site links are wrong. We SHOULD have used the localization friendly way to do this.

[Colstuwjx]

We SHOULD have used the localization friendly way to do this.

Yes, I was also wondering about this. I don't have any idea about which is the right way to do this, so I leave a comment on hugo repo, maybe hugo dev could give us some suggestions.

[tanjunchen]

We SHOULD have used the localization friendly way to do this.

+1
@Colstuwjx I have no good idea.

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[tengqm]

still relevant.
/remove-lifecycle rotten

[irvifa]

@tengqm would you like to help us for this issue? I was wondering what else needed besides the config itself.

[tengqm]

@irvifa Please check PR #19526 for the proposed changes.

[sftim]

My number 1 favorite approach would be for a localization team to write something like:

* 进一步了解 [控制器](/docs/concepts/architecture/controller/)

and for the generated HTML to link to https://kubernetes.io/zh/docs/concepts/architecture/controller/ (or whatever language code is appropriate.

If Hugo can't yet do this, it might even be feasible to look into tweaking Hugo itself.

[sftim]

/reopen

Oops. Misclick.

[k8s-ci-robot]

@sftim: Reopened this issue.

In response to this:

/reopen

Oops. Misclick.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[irvifa]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-contributor-experience at kubernetes/community.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-contributor-experience at kubernetes/community.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[Andygol]

I would like to /reopen this ticket in light of Hugo's ability to render links via https://gohugo.io/render-hooks/links/. This option can be used to implicitly add a language prefix to links. Thus, all valid Markdown links [text](/docs/…) in the text can receive a language prefix if there is a localized document.

Any advice and suggestions are welcome 🙏

PS. My WIP is here Andygol#160 🚧

[Andygol]

@sftim 🛎️ ☝️

[sftim]

Ack. I've seen the message @Andygol.