Website: Issue in l10n docs referencing EN layouts outside l10n working directory

[seokho-son]

This is a...

• [x] Feature Request
• [ ] Bug Report

Problem:
Documents, which l10n teams translate, include Layouts that shows some English description.
English inside Layout (e.g., partials/templates, shortcodes) cause some incomplete translation in l10n work.

For instance,
https://kubernetes.io/ko/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#before-you-begin
This translated document includes "Before you begin" in English.
"Before you begin" is from website/layouts/partials/templates/task.html file which is outside l10n working directory (e.g., website/content/ko).

Since l10n teams suppose to work in each l10n working directory, we are hard to translate English in Layouts.

Proposed Solution:
I think there are several options.

0) use .toml in i18n directory. Make English content in Layout files be a variable in .toml.

For example, we can change "Feedback" string in layouts/partials/feedback.html  to a variable defined in en.toml.

[i18n/**en**.toml]
# English usded in Layouts
[layout_partials_feedback]
other = "**Feedback**"

[i18n/**ko**.toml]
# English usded in Layouts
[layout_partials_feedback]
other = "**피드백 (Korean)**"

[layouts/partials/feedback.html]
{{ if not .Params.hide_feedback }}
  <h2>**{{ T "layout_partials_feedback" }}**</h2>
  <p class="feedback--prompt">Was this page helpful?</p>

1) modify the files in Layouts so that each file includes l10n sections.

For example, we can modify website/layouts/partials/templates/task.html file as follows

{{ $pageLang := .page.Language.Lang }} 

{{ if eq $pageLang ("**ko**") }}
{{ .ctx.Scratch.Add "blocks" (dict "page" .page "block" "prerequisites" "heading" "**시작하기 전에(Korean)**" "purpose" "lists action prerequisites and knowledge prerequisites.")  }}

{{ else if eq $pageLang ("**en**") }}
{{ .ctx.Scratch.Add "blocks" (dict "page" .page "block" "prerequisites" "heading" "**Before you begin**" "purpose" "lists action prerequisites and knowledge prerequisites.")  }}
{{ end }} 

2) change a HUGO configuration or repository structure to support multilingual layout somehow.

3) guide not to translate sections related with Layouts.

4) remove English words inside Layout files later on.

5) any nice idea !

Page to Update:
https://kubernetes.io/...

/sig docs

[kbhawkey]

Hello. There may be a few ways to do this, but just tried this:
1) Add some localized text to your .toml files for each heading text,

en.toml

testing localized what's next heading

[docs_whats_next]
other = "What's next, English?"

ko.toml

testing localized what's next heading

[docs_whats_next]
other = "What's next, Korean?"

2) Then update the partial html code, for example concept.html:
{{ $a := i18n "docs_whats_next" . }}
Use the new variable as the heading string:
{{ .ctx.Scratch.Add "blocks" (dict "page" .page "block" "whatsnext" "heading" $a "optional" true ) }}

[seokho-son]

@kbhawkey Thank you for your comment :+1:
I agree with you. Your solution is same with the option 0 that I described.
I also tested it in a similar way :) It works.
But I am not sure everyone (sig-docs) agree with this solution yet.

[jimangel]

I like the idea of option 1, where we can consolidate all of the localization in the same short codes and have "one 'master' source" to work out of for everyone. Hopefully this would decrease overhead and encourage consistency across repos. I think this would avoid everyone solving the same issue different ways. It's also very possible I don't fully understand the benefit of option 0 :).

I've added this for discussion on the 1/15 sig-docs meeting agenda.

[seokho-son]

Thank you @jimangel !!
I think both option 0 and option 1 are feasible. but like you said, I am not sure the consistency and efficiency in terms of management. So, it is nice to know this issue's been added in the meeting agenda. Thank you. I will be in the 1/15 sig-doc meeting as well :)

[jimangel]

Per our sig-docs meeting, consensus is option 0 (see referenced PR for fix). Thanks!