From bd79b6e6d31279fc4e29638ee6c78555bd94a5e1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 3 Jul 2024 13:28:57 -0400 Subject: [PATCH 1/3] Add i18n guidance re. images & shortcodes + some rework --- content/en/docs/contributing/localization.md | 80 +++++++++++++++----- 1 file changed, 59 insertions(+), 21 deletions(-) diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md index edcc9a62be6d..caa35d9d1744 100644 --- a/content/en/docs/contributing/localization.md +++ b/content/en/docs/contributing/localization.md @@ -1,45 +1,83 @@ --- title: Site localization -description: - Guidance on creating and maintaining site page in non-English localizations. +description: Creating and maintaining site pages in non-English localizations. linkTitle: Localization weight: 25 +cSpell:ignore: shortcodes --- -{{% pageinfo color="warning" %}} - -🚧 This DRAFT page is under active development. 🚧 - -{{% /pageinfo %}} - -This website uses Hugo's [multilingual framework] to support page localizations. +The OTel website uses Hugo's [multilingual framework] to support page localizations. English is the default language, with US English as the default (implicit) localization. A growing number of other localizations are supported, as can be seen from the languages dropdown menu in the top nav. -## Translation tips +## Translation guidance + +We recommend that you follow the guidance offered in this section when +translating pages. + +### Heading anchors + +To ensure that heading anchor targets are uniform across localizations, when +translating headings: + +- Preserve the heading's explicit ID if it has one. [Heading ID syntax] is + written after the heading text using syntax like `{ #some-id }` +- Otherwise, explicitly declare a heading ID corresponding to the autogenerated + ID of the original English heading. + +{{% alert title="Note" %}} + +We leave it to the discretion of localization authors to decide if they add an +explicit heading ID to all headings of translated pages, or whether this is only +done for known intra-site heading targets -- as reported by the link checker. +The former is more uniform and more work, but better supports having +site-external targets into localization pages, and avoids having to revisit +previously translated pages as new heading targets are used. -When you translate page content, follow this guidance: +{{% /alert %}} + +[Heading ID syntax]: + https://github.com/yuin/goldmark/blob/master/README.md#headings + +### Links -- To ensure that heading anchor targets are uniform across localizations, when - translating headings: - - If the heading has an explicit ID (which is of the form `{ #some-id }` and - comes after the heading text), then preserve the given ID - - Otherwise, include a heading ID corresponding to the original English - heading text. -- For link references that are local paths, preserve the path _as is_. +For link references to local paths (as opposed to external links), preserve the +path _as is_. This holds true for links to website pages or section-local +resources such as images. {{% alert title="Note" %}} -This repository has a custom render-link hook that Hugo uses to convert -**absolute link paths to documentation pages** that are of the form +The OTel website repository has a custom render-link hook that Hugo uses to +convert **absolute link paths to documentation pages** that are of the form `/docs/some-page`, to be locale specific, by prefixing the path with page language code when rendering the link. For example, the previous sample path would become `/ja/docs/some-page` when rendered from a Japanese page. {{% /alert %}} -## Keeping track of localized page drift {#track-changes} +### Images + +Hugo is smart in the way that it renders page images that are shared across site +localizations. That is, in the generated site folder, Hugo will output a +_single_ image file that is then shared across localizations. + +So as a general rule, _do not_ make copies of image files in your localization +unless you actually change the image. + +### Shortcodes + +Some of the base shortcodes contain English text that you might need to localize +-- this is particularly true of those contain in [layouts/shortcodes/docs]. + +If you need to create a localized version of a shortcode, place it under +`layouts/shortcodes/xx`, where `xx` is your localization's language code. From +there, use the same relative path as the original base shortcode. + +[layouts/shortcodes/docs]: + https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs + +## Keeping track of localized-page drift {#track-changes} One of the main challenges of maintaining localized pages, is identifying when the corresponding English language pages have been updated. This section From 472b702c7736b922d140a3e37a58994ce136c611 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 4 Jul 2024 12:27:43 -0400 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> --- content/en/docs/contributing/localization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md index caa35d9d1744..e5d3cfbc780c 100644 --- a/content/en/docs/contributing/localization.md +++ b/content/en/docs/contributing/localization.md @@ -22,7 +22,7 @@ To ensure that heading anchor targets are uniform across localizations, when translating headings: - Preserve the heading's explicit ID if it has one. [Heading ID syntax] is - written after the heading text using syntax like `{ #some-id }` + written after the heading text using syntax like `{ #some-id }`. - Otherwise, explicitly declare a heading ID corresponding to the autogenerated ID of the original English heading. @@ -30,9 +30,9 @@ translating headings: We leave it to the discretion of localization authors to decide if they add an explicit heading ID to all headings of translated pages, or whether this is only -done for known intra-site heading targets -- as reported by the link checker. -The former is more uniform and more work, but better supports having -site-external targets into localization pages, and avoids having to revisit +done for known intra-site heading targets, as reported by the link checker. +The former option is more uniform and more work. It better supports having +site-external targets into localization pages and avoids having to revisit previously translated pages as new heading targets are used. {{% /alert %}} @@ -49,8 +49,8 @@ resources such as images. {{% alert title="Note" %}} The OTel website repository has a custom render-link hook that Hugo uses to -convert **absolute link paths to documentation pages** that are of the form -`/docs/some-page`, to be locale specific, by prefixing the path with page +convert **absolute link paths to documentation pages**. Links of the form +`/docs/some-page` are made locale specific by prefixing the path with the page language code when rendering the link. For example, the previous sample path would become `/ja/docs/some-page` when rendered from a Japanese page. @@ -68,7 +68,7 @@ unless you actually change the image. ### Shortcodes Some of the base shortcodes contain English text that you might need to localize --- this is particularly true of those contain in [layouts/shortcodes/docs]. +-- this is particularly true of those contained in [layouts/shortcodes/docs]. If you need to create a localized version of a shortcode, place it under `layouts/shortcodes/xx`, where `xx` is your localization's language code. From From b8802d84269061d4a23d38d7be2b26fcca0c553f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 4 Jul 2024 12:34:56 -0400 Subject: [PATCH 3/3] Fix format --- content/en/docs/contributing/localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md index e5d3cfbc780c..4a88cc7f00ec 100644 --- a/content/en/docs/contributing/localization.md +++ b/content/en/docs/contributing/localization.md @@ -30,8 +30,8 @@ translating headings: We leave it to the discretion of localization authors to decide if they add an explicit heading ID to all headings of translated pages, or whether this is only -done for known intra-site heading targets, as reported by the link checker. -The former option is more uniform and more work. It better supports having +done for known intra-site heading targets, as reported by the link checker. The +former option is more uniform and more work. It better supports having site-external targets into localization pages and avoids having to revisit previously translated pages as new heading targets are used.