Skip to content

Commit f2a520b

Browse files
authored
[i18n] Update Do's and Don'ts of Localization guidance (open-telemetry#6483)
1 parent 2f99eb6 commit f2a520b

File tree

2 files changed

+38
-8
lines changed

2 files changed

+38
-8
lines changed

content/en/docs/contributing/localization.md

+34-8
Original file line numberDiff line numberDiff line change
@@ -16,24 +16,48 @@ as can be seen from the languages dropdown menu in the top nav.
1616
When translating website pages from English, we recommend that you follow the
1717
guidance offered in this section.
1818

19-
### Summary / TL;DR {#summary}
19+
### Summary
2020

21-
Do translate:
21+
#### Do {#do}
2222

23-
- [Front matter][] fields `title`, `linkTitle`, and `description`
24-
- Page content, including the text fields in Mermaid [diagrams](#images)
23+
<div class="border-start border-success bg-success-subtle">
2524

26-
Do **NOT**:
25+
- **Translate**:
26+
- Page content, including:
27+
- Mermaid [diagram](#images) text fields
28+
- Code comments from code excerpts
29+
- [Front matter][] field values for `title`, `linkTitle`, and `description`
30+
- **All** page content and front matter unless indicated otherwise
31+
- **Preserve** the _content_, _meaning_, and _style_ of the original text
32+
- **Ask** [maintainers] if you have any doubts or questions through:
33+
- [Slack] `#otel-docs-localization` or `#otel-comms` channels
34+
- [Discussion], issue, or PR comment
2735

28-
- Translate:
36+
[Discussion]:
37+
https://github.com/open-telemetry/opentelemetry.io/discussions?discussions_q=is%3Aopen+label%3Ai18n
38+
39+
</div>
40+
41+
#### ❌ Do NOT {#do-not}
42+
43+
<div class="border-start border-warning bg-warning-subtle">
44+
45+
- **Translate**:
2946
- **File or directory** names of resources in this repository
3047
- [Links](#links), this includes [heading IDs](#headings).[^*]
31-
- [Front matter][] fields other than those listed in the "Do" section above.
32-
In particular, do not translate `aliases`. When in doubt, ask maintainers.
48+
- [Front matter][] fields other than those listed in [Do](#do). In particular,
49+
do not translate `aliases`. When in doubt, ask maintainers.
50+
- Code
3351
- Create **copies of images**, unless you [localize text in the images](#images)
52+
- Add new or change:
53+
- **Content** that would be different from the originally intended meaning
54+
- Presentation **style**, including: _formatting_, _layout_, and _design_
55+
style (typography, letter case, and spacing for example).
3456

3557
[^*]: For a possible exception, see [Links](#links).
3658

59+
</div>
60+
3761
### Heading IDs {#headings}
3862

3963
To ensure that heading anchor targets are uniform across localizations, when
@@ -321,5 +345,7 @@ non-English pages. When this happens:
321345

322346
[front matter]: https://gohugo.io/content-management/front-matter/
323347
[main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
348+
[maintainers]: https://github.com/orgs/open-telemetry/teams/docs-maintainers
324349
[multilingual framework]: https://gohugo.io/content-management/multilingual/
325350
[PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files
351+
[slack]: https://slack.cncf.io/

static/refcache.json

+4
Original file line numberDiff line numberDiff line change
@@ -11915,6 +11915,10 @@
1191511915
"StatusCode": 206,
1191611916
"LastSeen": "2025-02-01T07:10:54.768801-05:00"
1191711917
},
11918+
"https://github.com/orgs/open-telemetry/teams/docs-maintainers": {
11919+
"StatusCode": 206,
11920+
"LastSeen": "2025-03-06T11:21:47.300632-05:00"
11921+
},
1191811922
"https://github.com/orgs/open-telemetry/teams/sig-contributor-experience-maintainers": {
1191911923
"StatusCode": 206,
1192011924
"LastSeen": "2025-01-31T13:07:53.320508201Z"

0 commit comments

Comments
 (0)