Skip to content

Commit cd571e5

Browse files
authored
[i18n] Make absolute paths locale-specific by default (#4689)
1 parent 508a3ed commit cd571e5

File tree

4 files changed

+84
-24
lines changed

4 files changed

+84
-24
lines changed

content/en/docs/contributing/localization.md

+22
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,28 @@ English is the default language, with US English as the default (implicit) local
1717
A growing number of other localizations are supported, as can be seen from the languages
1818
dropdown menu in the top nav.
1919

20+
## Translation tips
21+
22+
When you translate page content, follow this guidance:
23+
24+
- To ensure that heading anchor targets are uniform across localizations, when
25+
translating headings:
26+
- If the heading has an explicit ID (which is of the form `{ #some-id }` and
27+
comes after the heading text), then preserve the given ID
28+
- Otherwise, include a heading ID corresponding to the original English
29+
heading text.
30+
- For link references that are local paths, preserve the path _as is_.
31+
32+
{{% alert title="Note" %}}
33+
34+
This repository has a custom render-link hook that Hugo uses to convert
35+
**absolute link paths to documentation pages** that are of the form
36+
`/docs/some-page`, to be locale specific, by prefixing the path with page
37+
language code when rendering the link. For example, the previous sample path
38+
would become `/ja/docs/some-page` when rendered from a Japanese page.
39+
40+
{{% /alert %}}
41+
2042
## Keeping track of localized page drift {#track-changes}
2143

2244
One of the main challenges of maintaining localized pages, is identifying when

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

+13-13
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ default_lang_commit: d638c386
66
---
77

88
OpenTelemetry
9-
是一个[可观测性](/zh/docs/concepts/observability-primer/#what-is-observability)框架和工具包,
10-
旨在创建和管理遥测数据,如[链路](/zh/docs/concepts/signals/traces/)
11-
[指标](/zh/docs/concepts/signals/metrics/)[日志](/zh/docs/concepts/signals/logs/)
9+
是一个[可观测性](/docs/concepts/observability-primer/#what-is-observability)框架和工具包,
10+
旨在创建和管理遥测数据,如[链路](/docs/concepts/signals/traces/)
11+
[指标](/docs/concepts/signals/metrics/)[日志](/docs/concepts/signals/logs/)
1212
重要的是,OpenTelemetry 是供应商和工具无关的,这意味着它可以与各种可观测性后端一起使用,
1313
包括 [Jaeger](https://www.jaegertracing.io/)
1414
[Prometheus](https://prometheus.io/) 这类开源工具以及商业化产品。
@@ -20,7 +20,7 @@ OpenTelemetry 专注于遥测数据的生成、采集、管理和导出。 OpenT
2020

2121
## 什么是可观测性? {#what-is-observability}
2222

23-
[可观测性](/zh/docs/concepts/observability-primer/#what-is-observability)具备检查系统输出来理解系统内部状态的能力。
23+
[可观测性](/docs/concepts/observability-primer/#what-is-observability)具备检查系统输出来理解系统内部状态的能力。
2424
在软件的上下文中,这意味着通过检查遥测数据(包括链路、指标和日志)来理解系统的内部状态。
2525

2626
要使系统可观测,必须对其进行仪表化。也就是说,代码必须发出链路、指标或日志。
@@ -48,14 +48,14 @@ OpenTelemetry 包括以下主要组件:
4848
- 定义遥测数据形状的标准[协议](/docs/specs/otlp/)
4949
- 为常见遥测数据类型定义标准命名方案的[语义约定](/docs/specs/semconv/)
5050
- 定义如何生成遥测数据的 API
51-
- 实现规范、API 和遥测数据导出的[语言 SDK](/zh/docs/languages)
51+
- 实现规范、API 和遥测数据导出的[语言 SDK](/docs/languages)
5252
- 实现常见库和框架的仪表化的[库生态系统](/ecosystem/registry)
5353
- 可自动生成遥测数据的自动仪表化组件,无需更改代码
54-
- [OpenTelemetry Collector](/zh/docs/collector):接收、处理和导出遥测数据的代理
54+
- [OpenTelemetry Collector](/docs/collector):接收、处理和导出遥测数据的代理
5555
- 各种其他工具,
56-
[用于 Kubernetes 的 OpenTelemetry Operator](/zh/docs/kubernetes/operator/)
57-
[OpenTelemetry Helm Charts](/zh/docs/kubernetes/helm/)
58-
[FaaS 的社区资产](/zh/docs/faas/)
56+
[用于 Kubernetes 的 OpenTelemetry Operator](/docs/kubernetes/operator/)
57+
[OpenTelemetry Helm Charts](/docs/kubernetes/helm/)
58+
[FaaS 的社区资产](/docs/faas/)
5959

6060
OpenTelemetry 广泛应用于许多已集成 OpenTelemetry
6161
提供默认可观测性的[库、服务和应用](/ecosystem/integrations/)
@@ -69,7 +69,7 @@ OpenTelemetry 被设计为可扩展的。一些扩展 OpenTelemetry 的例子包
6969

7070
- 向 OpenTelemetry Collector 添加接收器以支持来自自定义源的遥测数据
7171
- 将自定义仪表化库加载到 SDK 中
72-
- 创建适用于特定用例的 SDK 或 Collector 的[分发](/zh/docs/concepts/distributions/)
72+
- 创建适用于特定用例的 SDK 或 Collector 的[分发](/docs/concepts/distributions/)
7373
- 为尚不支持 OpenTelemetry 协议(OTLP)的自定义后端创建新的导出器
7474
- 为非标准上下文传播格式创建自定义传播器
7575

@@ -84,9 +84,9 @@ OpenTracing 和 OpenCensus 项目合并而诞生的。OpenTracing 和 OpenCensus
8484
吸收了双方的优势,提供了统一的解决方案。
8585

8686
如果你目前正在使用 OpenTracing 或 OpenCensus,
87-
你可以在[迁移指南](/zh/docs/migration/)中了解如何迁移到 OpenTelemetry。
87+
你可以在[迁移指南](/docs/migration/)中了解如何迁移到 OpenTelemetry。
8888

8989
## 接下来做什么? {#what-next}
9090

91-
- 参阅[入门指南](/zh/docs/getting-started/) — 立即开始!
92-
- 了解 [OpenTelemetry 的概念](/zh/docs/concepts/)
91+
- 参阅[入门指南](/docs/getting-started/) — 立即开始!
92+
- 了解 [OpenTelemetry 的概念](/docs/concepts/)

layouts/_default/_markup/render-link.html

+48-10
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,62 @@
1-
{{ $isExternal := hasPrefix .Destination "http" -}}
1+
{{ $url := .Destination -}}
2+
3+
{{/*
4+
5+
Localization link processing
6+
7+
The following code block will prefix the page language code to an
8+
absolute path when:
9+
10+
- This page's localization isn't the default localization (English)
11+
- The URL is an absolute path that doesn't start with any of the following:
12+
- A language code, such as `ja`
13+
- A path segment other than `docs`, since current OTel localizations only
14+
offer translations for at most doc pages.
15+
16+
*/ -}}
17+
18+
{{ $defaultLang := "en" -}} {{/* TODO: can we avoid hard coding this value? */ -}}
19+
{{ $lang := .Page.Language.Lang -}}
20+
{{ if ne $lang $defaultLang -}}
21+
{{ $langPathPrefix := add "/" $lang "/" -}}
22+
{{ if and (hasPrefix $url $langPathPrefix) .Page.File -}}
23+
{{ warnf "File %s: avoid prefixing the following link path with '%s': %s"
24+
.Page.File.Filename $langPathPrefix $url -}}
25+
{{ else if and (hasPrefix $url "/")
26+
(not (findRE "^/(blog|community|docs/specs|ecosystem|status)/?" $url))
27+
-}}
28+
{{ if and false (not (findRE "^/[a-z][a-z](-[a-zA-Z]{2})?/" $url)) -}}
29+
{{ $url = add $langPathPrefix (strings.TrimPrefix "/" $url) -}}
30+
{{ end -}}
31+
{{ end -}}
32+
{{ end -}}
33+
34+
35+
{{/* General link-render processing */ -}}
36+
37+
{{ $url := .Destination -}}
38+
{{ $isExternal := hasPrefix $url "http" -}}
239
{{ if $isExternal -}}
3-
{{ if findRE "^https://opentelemetry.io/\\w" .Destination -}}
40+
{{ if findRE "^https://opentelemetry.io/\\w" $url -}}
441
{{ warnf "%s: use a local path, not an external URL, for the following reference to a site local page: %s"
5-
.Page.File.Path .Destination -}}
42+
.Page.File.Path $url -}}
643
{{ else if or
7-
(findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" .Destination)
8-
(findRE "^https://github.com/open-telemetry/opentelemetry-proto/(blob|tree)/main/docs/specification" .Destination)
9-
(findRE "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs" .Destination)
44+
(findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" $url)
45+
(findRE "^https://github.com/open-telemetry/opentelemetry-proto/(blob|tree)/main/docs/specification" $url)
46+
(findRE "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs" $url)
1047
-}}
1148
{{ warnf "%s: use a local path, not an external URL, for the following reference to a local specification page: %s"
12-
.Page.File.Path .Destination -}}
49+
.Page.File.Path $url -}}
1350
{{ end -}}
1451
{{ end -}}
1552

1653
{{/* Until Hugo supports hook params (https://github.com/gohugoio/hugo/issues/6670), we'll inspect .Text. */ -}}
17-
{{ $noExternalIcon := in .Text "hk-no-external-icon" -}}
18-
<a href="{{ .Destination | safeURL }}"
54+
55+
<a href="{{ $url | safeURL }}"
1956
{{- with .Title}} title="{{ . }}"{{ end -}}
2057
{{- if $isExternal }} target="_blank" rel="noopener"
21-
{{- if not $noExternalIcon }} class="external-link"{{ end -}}
58+
{{- $noExternalIcon := in .Text "hk-no-external-icon" -}}
59+
{{ if not $noExternalIcon }} class="external-link"{{ end -}}
2260
{{ end -}}
2361
>
2462
{{- .Text | safeHTML -}}

layouts/shortcodes/sampling-support-list.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@
66
{{- end }}
77

88
{{ define "list-item" -}}
9-
- [{{ .name }}]({{ .page.RelPermalink }})
9+
- <a href="{{ .page.RelPermalink }}">{{ .name }}</a>
1010
{{ end -}}

0 commit comments

Comments
 (0)