[i18n] Propose way to associate translations to specific commit of default lang page

[chalin]

• Originally posted by @chalin in [zh] Localize context-propagation.md #4536 (comment)

  Thank you for providing more context, and the reference to the K8s example.

  FYI, I've started two threads of discussion in the hopes of figuring out what "best practices" there might already be in use at the CNCF or elsewhere:

  • Internationalization (i18n) and localization (l10n) #4302 (comment)
  • https://cloud-native.slack.com/archives/CUJ6W5TLM/p1717149935431579

  Let me respond more to your suggestion to embed en page segments as HTML comments in zh pages in the thread of Internationalization (i18n) and localization (l10n) #4302 (comment).

• Via [zh] Localize context-propagation.md #4536 (comment):

  I second @windsonsea comment, this should be removed in the spirit of keeping things DRY. Otherwise, how do you know that the comment is up-to-date? You'll need to open the original file to double check anyways.

  Please remove all embedded HTML comments.

  What would be more useful would be to include, in the front matter, a permalink to the specific version (including the commit hash) of the en page that was used to create this translation, but we can discuss this separately. /cc @open-telemetry/docs-approvers

• Via Internationalization (i18n) and localization (l10n) #4302 (reply in thread), I, @chalin wrote:

  Being able to detect page drift between en and non-en pages is a challenging problem. @cjyabraham has made me aware of solutions used by other CNCF projects. I'll be reviewing those a reporting back here.

  In #4536 (comment), @my-git9 proposes to use the K8s zh localization approach of embedding en page segments in zh pages as HTML comments. I'd strongly vote against this approach because:

  1. The duplication and maintenance overhead of keeping those en language HTML comments up-to-date.
  2. Embedding en page segments as HTML only compounds the maintenance problem without helping us detect if there is a drift between en and zh pages.

  I'll be reviewing other CNCF-project approaches to this and report back here as soon as I can.

• Via same previous thread @my-git9 wrote:

  The k8s documentation community uses a script as a detection tool. The premise of using it requires the translator to standardize the commit. Perhaps we can refer to: https://github.com/kubernetes/website/blob/main/scripts/lsync.sh

Our support for translations is nascent. We have an opportunity to get it right, or at least good enough, from the start.

Let me put something together to show you what I have in mind. In the meantime, I'd suggest delaying the merge of other zh page translations.

Tasks

• [CI] Script to help know if localized pages need updating #4599
• [zh] Strip away embedded HTML en fragments #4602
• [i18n & CI] Add default_lang_commit to front matter of all non en pages #4612
• [i18n] Add contributing guidelines for localizations #4614
• [CI & i18n] GH action to run i18n-check + new fix GH action #4620

Related

• https://github.com/search?q=repo%3Akubernetes%2Fwebsite%20scripts%2Flsync.sh&type=code
• https://github.com/kubernetes/website/blob/main/scripts/lsync.sh
• https://github.com/kubernetes/website/tree/main/content

[chalin]

@open-telemetry/docs-maintainers - FYI, during today's Comms meeting we agreed to not / no longer merge non-en language pages containing embedded en-source page fragments as HTML comments. @svrnm - I assume that you'll follow up with the zh PRs that you merged before the meeting to ask them to strip the comments? Thanks!

[chalin]

I'm satsified with the proposed design and implementation, as documented in https://opentelemetry.io/docs/contributing/localization/. We'll continue to vet the approach and adjust as needed, but I'm closing-as-completed for now.