Skip to content

Commit f707587

Browse files
committed
[i18n] Update Do's and Don'ts of Localization guidance
1 parent bf05f8b commit f707587

File tree

1 file changed

+31
-7
lines changed

1 file changed

+31
-7
lines changed

content/en/docs/contributing/localization.md

+31-7
Original file line numberDiff line numberDiff line change
@@ -18,22 +18,44 @@ guidance offered in this section.
1818

1919
### Summary / TL;DR {#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+
- [Front matter][] fields `title`, `linkTitle`, and `description`
29+
- **All** page content and front matter unless indicated otherwise
30+
- **Preserve** the _content_, _meaning_, and _style_ of the original text
31+
- **Ask** [maintainers] if you have any doubts or questions through:
32+
- [Slack] `#otel-docs-localization` or `#otel-comms` channels
33+
- [Discussion], issue, or PR comment
2734

28-
- Translate:
35+
[Discussion]:
36+
https://github.com/open-telemetry/opentelemetry.io/discussions?discussions_q=is%3Aopen+label%3Ai18n
37+
38+
</div>
39+
40+
#### ❌ Do NOT {#do-not}
41+
42+
<div class="border-start border-warning bg-warning-subtle">
43+
44+
- **Translate**:
2945
- **File or directory** names of resources in this repository
3046
- [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.
47+
- [Front matter][] fields other than those listed in [Do](#do). In particular,
48+
do not translate `aliases`. When in doubt, ask maintainers.
3349
- Create **copies of images**, unless you [localize text in the images](#images)
50+
- Add new or change:
51+
- **Content** that would be different from the originally intended meaning
52+
- Presentation **style**, including: _formatting_, _layout_, and _design_ style
53+
(typography, letter case, and spacing for example).
3454

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

57+
</div>
58+
3759
### Heading IDs {#headings}
3860

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

322344
[front matter]: https://gohugo.io/content-management/front-matter/
323345
[main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
346+
[maintainers]: https://github.com/orgs/open-telemetry/teams/docs-maintainers
324347
[multilingual framework]: https://gohugo.io/content-management/multilingual/
325348
[PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files
349+
[slack]: https://slack.cncf.io/

0 commit comments

Comments
 (0)