Translating specs content (/docs/specs/) for locales — JA team interested

[ymotongpoo]

Context

The Japanese localization team wants to translate the spec pages under /docs/specs/ (OTel spec, OTLP, semantic conventions, OpAMP). The current build doesn't support this.

config/_default/module.yaml generates the English spec pages at build time from pinned submodules (content-modules/opentelemetry-specification, -proto, semantic-conventions, opamp-spec) into tmp/, then mounts them straight to content/docs/specs/... for the default language only. The file carries the comment # Specs, currently en only. Every other locale's English-fallback mount excludes this tree: files: ['! specs/**'].

This looks like a deliberate choice. Two reasons stand out:

• The spec tree is large and follows its own release cadence through submodule pins.
• The localization workflow tracks drift page-by-page (default_lang_commit, npm run check:i18n) against hand-authored static content. Content regenerated wholesale from external repos on every build doesn't fit that model.

Why we're asking

The JA team wants to translate spec content. Readers use specs as reference material, not just onboarding docs, and Japanese readers hit the same barrier as anyone reading a normative document in a second language.

Before we build a workaround, we want to know if maintainers ruled this out on purpose, or if nobody asked yet.

Questions

1. Did the team exclude specs from localization for a specific technical, editorial, or process reason?
2. If not, would maintainers accept a page-by-page approach: hand-translate select pages (overview, glossary) and override just those paths with a dedicated mount, the way otel-config/types.md already gets a single-file override today, without touching the submodule-generated tree or its pipeline?
3. Have other locale teams hit this same wall?

We can prototype a small example first if that helps decide.

[svrnm]

hi, thanks for bringing up this topic. The short answer from SIG Comms is, that we do not own the specification, this is sourced into the website via the spec repo, so if we talk about localization of this repo (or any other repo that we pull in), we need to start a conversation with @open-telemetry/specs-maintainers and @open-telemetry/technical-committee as we would need to coordinate that with them.

[svrnm]

@ymotongpoo just to add that, I suggest you open an issue with the spec and attend a spec meeting (if that is in any way compatible with your timezone) to kick off a discussion on that

[ymotongpoo]

@svrnm Thanks for the comment. I raised the topic in the spec repo. Unfortunately very few SIG meetings are friendly to my (APAC) timezone, which is a large topic in OTel community btw, so I can't make it to join the spec SIG meetings.

[chalin]

@ymotongpoo - keep us (SIG Comms / website team) in the loop about what gets decided by the specs team. If the spec team choses to support localized versions of the spec, we might need to rethink how the spec is published via the website.

[ymotongpoo]

Following up on the suggestions from @svrnm and @chalin: I opened a discussion in the spec repository to ask the spec maintainers and the TC about Japanese translations of the spec.

open-telemetry/opentelemetry-specification#5329

I will share the outcome here.