Implementation of the Link Decorator function for processing localised links 🈂️

[Andygol]

Description

I'm pleased to introduce the Link Decorator feature, which automatically transforms links in localised documents if the referenced documents have been localised. This feature eliminates the need to manually add language codes to links.

This was also inspired by the https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html template, which is already included in Hugo.

The logic is as follows

graph LR;

src_link("Link in a doc…")


src_link-->none_localized_link("… is not localized starts with /…")-->
check_for_localization{"if a localized
doc exists"}-- "yes, it is" -->add_lng_prefix("Add lang-code prefix to the link")

src_link-->indoc_link("… is in the same doc starts with # symbol")
src_link-->already_localized_link("… is already localized starts with /lang-code/…")
src_link-->ext_link("…is an external link starts with protocol [https:|mailto:|…] ")

ext_link & already_localized_link & indoc_link ---> asis("Keep it as is")
check_for_localization-- "no, it isn't" -->asis

Loading

The current approach fully implements the logic of link decoration by adding a language prefix to localised documents where it is not explicitly specified. Links with a hard-coded https://kubernetes.io/ or https://k8s.io/ are considered external and processed as such, even if there are localised versions of the link in the documentation. Handling such cases significantly complicates the code and processing time, and it is easier to correct such links directly in the text of documents.

I hope that the adoption of this PR will significantly improve the usability of the documentation and simplify the work of translators to maintain it.

Issue

This effort was inspired by a previous discussion about adding language code manually when localising documents. — #18403

/hold Depends on: PR #47612 — Fixed flag deprecations and updated Hugo version to latest

/cc @sftim as per your request in Slack.

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	a0ede94
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/66c6621707d88000089741b0
😎 Deploy Preview	https://deploy-preview-47620--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[tengqm]

Some clarifications:

• This code automagically works without having to revise any existing English pages, right?
• The existing language prefix added by localization teams still works with this code, right?
• The fallback to English page is transparent, right?
• Any statistics about the build time after introducing this code?

[Andygol]

Some clarifications:

• This code automagically works without having to revise any existing English pages, right?
• The existing language prefix added by localization teams still works with this code, right?
• The fallback to English page is transparent, right?
• Any statistics about the build time after introducing this code?

@tengqm
Absolutely, all already localized links works; in case you've referred translated documents but do not add language prefix explicitly, it will be added by decorator; if there's absent localized link, language code won't be added. After merging this PR manual addition of language codes will be deprecated. You may check Chinese test page https://deploy-preview-47620--kubernetes-io-main-staging.netlify.app/zh-cn/docs/test/.

See netlify response above to find build log.

UPD. The true functionality of this code can only be assessed after the Hugo is updated to the up-to-date version, see PR #47612.

[sftim]

/area web-development

Nice to see this arrive!

[Andygol]

/unhold

[Andygol]

As PR #47612 has been merged, feel free to review and approve this one as well🙏

[Andygol]

Re-run test to engage new build with updated Hugo
/test all

[k8s-ci-robot]

@Andygol: Cannot trigger testing until a trusted user reviews the PR and leaves an /ok-to-test message.

In response to this:

Re-run test to engage new build with updated Hugo
/test all

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-sigs/prow repository.

[sftim]

(aside) This repo does not really use Prow's /test command.

[Andygol]

(aside) This repo does not really use Prow's /test command.

🙄 It would be great to re-engage netlify build process somehow to streamline review.

[tengqm]

The only concern from me is about the build time overhead (supposing that all conversions are done during build time). However, as a standalone processor, we can easily disable it if it goes wrong.
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tengqm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [tengqm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Andygol]

Should anyone from sig-docs-website-owners add LGTM?

[steve-hardman]

Looks like a nice addition to help the localization teams.

/lgtm

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: d4effeeaf0186ad7a597d0d48a2120c621b36ea2

[sftim]

It would be great to re-engage netlify build process somehow to streamline review.

PRs welcome (from anyone)! But it's not a priority.