[i18n] Make absolute paths locale-specific by default

content/en/docs/contributing/localization.md

@@ -17,6 +17,28 @@ English is the default language, with US English as the default (implicit) local
 A growing number of other localizations are supported, as can be seen from the languages
 dropdown menu in the top nav.
 
+## Translation tips
+
+When you translate page content, follow this guidance:
+
+- 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_.
+
+{{% alert title="Note" %}}
+
+This repo 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}
 
 One of the main challenges of maintaining localized pages, is identifying when

content/zh/docs/what-is-opentelemetry.md

@@ -6,9 +6,9 @@ default_lang_commit: d638c386
 ---
 
 OpenTelemetry
-是一个[可观测性](/zh/docs/concepts/observability-primer/#what-is-observability)框架和工具包，
-旨在创建和管理遥测数据，如[链路](/zh/docs/concepts/signals/traces/)、
-[指标](/zh/docs/concepts/signals/metrics/)和[日志](/zh/docs/concepts/signals/logs/)。
+是一个[可观测性](/docs/concepts/observability-primer/#what-is-observability)框架和工具包，
+旨在创建和管理遥测数据，如[链路](/docs/concepts/signals/traces/)、
+[指标](/docs/concepts/signals/metrics/)和[日志](/docs/concepts/signals/logs/)。
 重要的是，OpenTelemetry 是供应商和工具无关的，这意味着它可以与各种可观测性后端一起使用，
 包括 [Jaeger](https://www.jaegertracing.io/) 和
 [Prometheus](https://prometheus.io/) 这类开源工具以及商业化产品。
@@ -20,7 +20,7 @@ OpenTelemetry 专注于遥测数据的生成、采集、管理和导出。 OpenT
 
 ## 什么是可观测性？ {#what-is-observability}
 
-[可观测性](/zh/docs/concepts/observability-primer/#what-is-observability)具备检查系统输出来理解系统内部状态的能力。
+[可观测性](/docs/concepts/observability-primer/#what-is-observability)具备检查系统输出来理解系统内部状态的能力。
 在软件的上下文中，这意味着通过检查遥测数据（包括链路、指标和日志）来理解系统的内部状态。
 
 要使系统可观测，必须对其进行仪表化。也就是说，代码必须发出链路、指标或日志。
@@ -48,14 +48,14 @@ OpenTelemetry 包括以下主要组件：
 - 定义遥测数据形状的标准[协议](/docs/specs/otlp/)
 - 为常见遥测数据类型定义标准命名方案的[语义约定](/docs/specs/semconv/)
 - 定义如何生成遥测数据的 API
-- 实现规范、API 和遥测数据导出的[语言 SDK](/zh/docs/languages)
+- 实现规范、API 和遥测数据导出的[语言 SDK](/docs/languages)
 - 实现常见库和框架的仪表化的[库生态系统](/ecosystem/registry)
 - 可自动生成遥测数据的自动仪表化组件，无需更改代码
-- [OpenTelemetry Collector](/zh/docs/collector)：接收、处理和导出遥测数据的代理
+- [OpenTelemetry Collector](/docs/collector)：接收、处理和导出遥测数据的代理
 - 各种其他工具，
-  如[用于 Kubernetes 的 OpenTelemetry Operator](/zh/docs/kubernetes/operator/)、
-  [OpenTelemetry Helm Charts](/zh/docs/kubernetes/helm/) 和
-  [FaaS 的社区资产](/zh/docs/faas/)
+  如[用于 Kubernetes 的 OpenTelemetry Operator](/docs/kubernetes/operator/)、
+  [OpenTelemetry Helm Charts](/docs/kubernetes/helm/) 和
+  [FaaS 的社区资产](/docs/faas/)
 
 OpenTelemetry 广泛应用于许多已集成 OpenTelemetry
 提供默认可观测性的[库、服务和应用](/ecosystem/integrations/)。
@@ -69,7 +69,7 @@ OpenTelemetry 被设计为可扩展的。一些扩展 OpenTelemetry 的例子包
 
 - 向 OpenTelemetry Collector 添加接收器以支持来自自定义源的遥测数据
 - 将自定义仪表化库加载到 SDK 中
-- 创建适用于特定用例的 SDK 或 Collector 的[分发](/zh/docs/concepts/distributions/)
+- 创建适用于特定用例的 SDK 或 Collector 的[分发](/docs/concepts/distributions/)
 - 为尚不支持 OpenTelemetry 协议（OTLP）的自定义后端创建新的导出器
 - 为非标准上下文传播格式创建自定义传播器
 
@@ -84,9 +84,9 @@ OpenTracing 和 OpenCensus 项目合并而诞生的。OpenTracing 和 OpenCensus
 吸收了双方的优势，提供了统一的解决方案。
 
 如果你目前正在使用 OpenTracing 或 OpenCensus，
-你可以在[迁移指南](/zh/docs/migration/)中了解如何迁移到 OpenTelemetry。
+你可以在[迁移指南](/docs/migration/)中了解如何迁移到 OpenTelemetry。
 
 ## 接下来做什么？ {#what-next}
 
-- 参阅[入门指南](/zh/docs/getting-started/) — 立即开始！
-- 了解 [OpenTelemetry 的概念](/zh/docs/concepts/)。
+- 参阅[入门指南](/docs/getting-started/) — 立即开始！
+- 了解 [OpenTelemetry 的概念](/docs/concepts/)。

layouts/_default/_markup/render-link.html

@@ -1,24 +1,62 @@
-{{ $isExternal := hasPrefix .Destination "http" -}}
+{{ $url := .Destination -}}
+
+{{/*
+
+  Localization link processing
+
+  The following code block will prefix the page language code to an
+  absolute path when:
+
+  - This page's localization isn't the default localization (English)
+  - The URL is an absolute path that doesn't start with any of the following:
+    - A language code, such as `ja`
+    - A path segment other than `docs`, since current OTel localizations only
+      offer translations for at most doc pages.
+
+  */ -}}
+
+{{ $defaultLang := "en" -}} {{/* TODO: can we avoid hard coding this value? */ -}}
+{{ $lang := .Page.Language.Lang -}}
+{{ if ne $lang $defaultLang -}}
+  {{ $langPathPrefix := add "/" $lang "/" -}}
+  {{ if and (hasPrefix $url $langPathPrefix) .Page.File -}}
+    {{ warnf "File %s: avoid prefixing the following link path with '%s': %s"
+             .Page.File.Filename $langPathPrefix $url -}}
+  {{ else if and (hasPrefix $url "/")
+            (not (findRE "^/(blog|community|docs/specs|ecosystem|status)/?" $url))
+  -}}
+    {{ if and false (not (findRE "^/[a-z][a-z](-[a-zA-Z]{2})?/" $url)) -}}
+      {{ $url = add $langPathPrefix (strings.TrimPrefix "/" $url) -}}
+    {{ end -}}
+  {{ end -}}
+{{ end -}}
+
+
+{{/* General link-render processing */ -}}
+
+{{ $url := .Destination -}}
+{{ $isExternal := hasPrefix $url "http" -}}
 {{ if $isExternal -}}
-  {{ if findRE "^https://opentelemetry.io/\\w" .Destination -}}
+  {{ if findRE "^https://opentelemetry.io/\\w" $url -}}
     {{ warnf "%s: use a local path, not an external URL, for the following reference to a site local page: %s"
-        .Page.File.Path .Destination -}}
+        .Page.File.Path $url -}}
   {{ else if or
-    (findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" .Destination)
-    (findRE "^https://github.com/open-telemetry/opentelemetry-proto/(blob|tree)/main/docs/specification" .Destination)
-    (findRE "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs" .Destination)
+    (findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" $url)
+    (findRE "^https://github.com/open-telemetry/opentelemetry-proto/(blob|tree)/main/docs/specification" $url)
+    (findRE "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs" $url)
     -}}
     {{ warnf "%s: use a local path, not an external URL, for the following reference to a local specification page: %s"
-    .Page.File.Path .Destination -}}
+    .Page.File.Path $url -}}
   {{ end -}}
 {{ end -}}
 
 {{/* Until Hugo supports hook params (https://github.com/gohugoio/hugo/issues/6670), we'll inspect .Text. */ -}}
-{{ $noExternalIcon := in .Text "hk-no-external-icon" -}}
-<a href="{{ .Destination | safeURL }}"
+
+<a href="{{ $url | safeURL }}"
   {{- with .Title}} title="{{ . }}"{{ end -}}
   {{- if $isExternal }} target="_blank" rel="noopener"
-    {{- if not $noExternalIcon }} class="external-link"{{ end -}}
+    {{- $noExternalIcon := in .Text "hk-no-external-icon" -}}
+    {{ if not $noExternalIcon }} class="external-link"{{ end -}}
   {{ end -}}
 >
   {{- .Text | safeHTML -}}

layouts/shortcodes/sampling-support-list.md

@@ -6,5 +6,5 @@
 {{- end }}
 
 {{ define "list-item" -}}
-- [{{ .name }}]({{ .page.RelPermalink }})
+- <a href="{{ .page.RelPermalink }}">{{ .name }}</a>
 {{ end -}}