Add i18n guidance re. images & shortcodes + some rework

content/en/docs/contributing/localization.md

@@ -1,45 +1,83 @@
 ---
 title: Site localization
-description:
-  Guidance on creating and maintaining site page in non-English localizations.
+description: Creating and maintaining site pages in non-English localizations.
 linkTitle: Localization
 weight: 25
+cSpell:ignore: shortcodes
 ---
 
-{{% pageinfo color="warning" %}}
-
-🚧 This DRAFT page is under active development. 🚧
-
-{{% /pageinfo %}}
-
-This website uses Hugo's [multilingual framework] to support page localizations.
+The OTel website uses Hugo's [multilingual framework] to support page localizations.
 English is the default language, with US English as the default (implicit) localization.
 A growing number of other localizations are supported, as can be seen from the languages
 dropdown menu in the top nav.
 
-## Translation tips
+## Translation guidance
+
+We recommend that you follow the guidance offered in this section when
+translating pages.
+
+### Heading anchors
+
+To ensure that heading anchor targets are uniform across localizations, when
+translating headings:
+
+- Preserve the heading's explicit ID if it has one. [Heading ID syntax] is
+  written after the heading text using syntax like `{ #some-id }`.
+- Otherwise, explicitly declare a heading ID corresponding to the autogenerated
+  ID of the original English heading.
+
+{{% alert title="Note" %}}
+
+We leave it to the discretion of localization authors to decide if they add an
+explicit heading ID to all headings of translated pages, or whether this is only
+done for known intra-site heading targets, as reported by the link checker. The
+former option is more uniform and more work. It better supports having
+site-external targets into localization pages and avoids having to revisit
+previously translated pages as new heading targets are used.
 
-When you translate page content, follow this guidance:
+{{% /alert %}}
+
+[Heading ID syntax]:
+  https://github.com/yuin/goldmark/blob/master/README.md#headings
+
+### Links
 
-- 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_.
+For link references to local paths (as opposed to external links), preserve the
+path _as is_. This holds true for links to website pages or section-local
+resources such as images.
 
 {{% alert title="Note" %}}
 
-This repository 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
+The OTel website repository has a custom render-link hook that Hugo uses to
+convert **absolute link paths to documentation pages**. Links of the form
+`/docs/some-page` are made locale specific by prefixing the path with the 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}
+### Images
+
+Hugo is smart in the way that it renders page images that are shared across site
+localizations. That is, in the generated site folder, Hugo will output a
+_single_ image file that is then shared across localizations.
+
+So as a general rule, _do not_ make copies of image files in your localization
+unless you actually change the image.
+
+### Shortcodes
+
+Some of the base shortcodes contain English text that you might need to localize
+-- this is particularly true of those contained in [layouts/shortcodes/docs].
+
+If you need to create a localized version of a shortcode, place it under
+`layouts/shortcodes/xx`, where `xx` is your localization's language code. From
+there, use the same relative path as the original base shortcode.
+
+[layouts/shortcodes/docs]:
+  https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
+
+## Keeping track of localized-page drift {#track-changes}
 
 One of the main challenges of maintaining localized pages, is identifying when
 the corresponding English language pages have been updated. This section