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.