From 9fbf1abcd82a6389063b0357c0c0147f0faca249 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jun 2024 17:52:03 -0400 Subject: [PATCH] [i18n] Make absolute paths locale-specific by default --- content/en/docs/contributing/localization.md | 22 ++++++++ content/zh/docs/what-is-opentelemetry.md | 26 ++++----- layouts/_default/_markup/render-link.html | 58 ++++++++++++++++---- layouts/shortcodes/sampling-support-list.md | 2 +- 4 files changed, 84 insertions(+), 24 deletions(-) diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md index c66647d64a59..b71930f159f5 100644 --- a/content/en/docs/contributing/localization.md +++ b/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 diff --git a/content/zh/docs/what-is-opentelemetry.md b/content/zh/docs/what-is-opentelemetry.md index 9f4d28ff5d45..ef8c52d78a56 100644 --- a/content/zh/docs/what-is-opentelemetry.md +++ b/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/)。 diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index 16b2c1173fb0..a79c7797b781 100644 --- a/layouts/_default/_markup/render-link.html +++ b/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" -}} - {{- .Text | safeHTML -}} diff --git a/layouts/shortcodes/sampling-support-list.md b/layouts/shortcodes/sampling-support-list.md index a827f8850200..6ae3c7f3aa02 100644 --- a/layouts/shortcodes/sampling-support-list.md +++ b/layouts/shortcodes/sampling-support-list.md @@ -6,5 +6,5 @@ {{- end }} {{ define "list-item" -}} -- [{{ .name }}]({{ .page.RelPermalink }}) +- {{ .name }} {{ end -}}