Japanese translation of the OpenTelemetry specification on opentelemetry.io

[ymotongpoo]

Summary

The Japanese localization team of opentelemetry.io (SIG Comms) wants to translate parts of the OpenTelemetry specification into Japanese and publish them on opentelemetry.io under /ja/docs/specs/. SIG Comms told us that the spec belongs to the spec maintainers and the Technical Committee, so we need your agreement before we start. This discussion asks for that agreement and for your guidance on how translations should relate to the English spec.

Background discussion on the website side: open-telemetry/opentelemetry.io#11484

Context

• opentelemetry.io builds /docs/specs/otel/ from a pinned submodule of this repository. The build publishes the spec in English only, and every other locale excludes the spec tree.
• The Japanese team already translates and maintains a large part of the website docs under content/ja/. Each translated page records the English commit that it is based on, so we can detect when a translation falls behind the English source.
• Readers use the spec as reference material. Japanese readers find normative text in a second language hard to read, especially the precise meaning of requirement levels and data model definitions.

What we propose

1. English stays authoritative. Translated pages are informative only. Each page shows a notice that the English version is normative and links to it.
2. No new work for spec maintainers. The Japanese team writes, reviews, and maintains the translations in the opentelemetry.io repository. We do not propose to add translated files or new review requirements to this repository.
3. Start small. We begin with a few stable, high-traffic pages (for example, the overview and the glossary), not the whole spec.
4. Track the English version. Each translation records the spec version or commit it is based on. When the English page changes, the website tooling marks the translation as out of date.
5. Keep requirement keywords unambiguous. We keep the BCP 14 keywords (MUST, SHOULD, MAY, and so on) in English in the translated text, so a translation cannot change the requirement level.

Questions for spec maintainers and the TC

1. Do you agree that the Japanese team publishes translated spec pages on opentelemetry.io, with the conditions above?
2. Do you have a preference about where translations live (the website repository, as proposed, or this repository)?
3. Do you want any specific wording for the "English is normative" notice, or any pages that we must not translate (for example, pages in Development status that change often)?
4. Is there anything in the spec release process that we must follow, such as translating only released versions?

The same question also applies to OTLP, semantic conventions, and OpAMP, which opentelemetry.io publishes from other repositories. If you think those need separate discussions in their own repositories, please tell us.

I can also join a spec SIG meeting to discuss this if that is easier.

cc @open-telemetry/specs-maintainers @open-telemetry/technical-committee @open-telemetry/docs-approvers @open-telemetry/docs-ja-approvers

[pellared]

I am strongly against this proposal. Specification documents are not officially translated because English serves as the universal, unambiguous baseline for Internet standards. This helps maintain legal precision, technical consistency, and interoperability across the global tech sector.

Specifications require absolute syntactic and mathematical exactness. Translating words like "MUST", "SHOULD", or "MAY" (which have strict legal meanings under RFC 2119) into other languages can subtly alter their technical compliance boundaries. Even minor linguistic mismatches could lead to incompatible software implementations, fragmenting how parts of the software communicate with one another.

[ymotongpoo]

Thanks for the comments. I think this objection is arguing against something the proposal does not actually propose.

The proposal does not make translated text normative. The English specification remains authoritative, translations are explicitly informative, and BCP 14 keywords such as MUST, SHOULD, and MAY remain in English. So the specific ambiguity around normative requirements that you describe is already accounted for.

More importantly, the argument seems to assume that if a translation cannot preserve every nuance of the source language with perfect precision, then providing the translation is inherently harmful. Taken seriously, that standard would make translation of essentially all technical documentation impossible. Precise terminology, context-dependent wording, and subtle semantic distinctions are not unique to the OpenTelemetry specification.

A translation does not need to become an independent source of normative truth in order to be useful. Its purpose is to lower the barrier to understanding the authoritative English text. If there is ever a discrepancy or ambiguity, the English specification wins. That is a well-understood and perfectly workable model.

So I do not think “translation may introduce nuance” is, by itself, a compelling argument against providing informative translations. It is an argument for clearly defining their non-normative status—which this proposal already does.

[pellared]

First, I want to apologize first as I think my message is too strong and I replied in a rush.

The important nuance is that I want to avoid that any translation of the specification would be considered "official" and normative. The specification maintainers and approvers would have no control over ensuring that these translations are correct. I see that this is already described in the proposal, but how do you want to be sure that this is well communicated?

I would like to understand more the motivation behind the purpose of these translations

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.

The translated documents would no longer be considered normative. Therefore, people that need these precise and normative requirements can be mislead by the translation. Wouldn't this defeat the motiviation behind translation of the specifcation?

Who are the people that want to read the specification in other languages? Are these OpenTelemetry users or OpenTelemetry contributors (e.g. maintainers). Maybe the issue is that the English docs of https://github.com/open-telemetry/opentelemetry.io/ should be more self-contained provide more information instead of referring to the specification in some places?

[svrnm]

just throwing in my five cents, as I can see both perspectives:

• Pro "localization": there is a big part of end users that are neither native english speakers nor are they proficient enough in it to read our documentation and even more our specification. That's not a question of skill, but depending on your mother tongue English might be a very foreign language to the reader, so a non-normative translation would lower that barrier for folks to follow the spec and get into the details.
• Contra "localitzation": I get the point that it must be CRYSTAL CLEAR that any form of localization never can be normative and will just be informativ, and that's hard to accomplish, even if you write it in big red letters people have the tendency to ignore that.

I think this is neither a "the one" or "the other" situation, and more one where we would need to see how big the gain is to do it and how big the "harm" would be on the flip side. I think, it would be very helpful to know, if there are localizations of other normative documents, and how they handle this situation. @ymotongpoo, can you provide some references of other projects, norms, etc that are localized and how they handle that?

[ymotongpoo]

Thanks, this is a useful question. I found a concrete CNCF example and one reader’s account of why an implementation-facing translation was useful.

Kubernetes publishes localized API references that describe implementation-facing API contracts. For example, the Chinese Kubernetes Pod API reference translates schema and field details such as requiredness and mutability. The Kubernetes Japanese site’s build notes also describe API reference pages generated from Swagger/OpenAPI.

There is also an independent Chinese translation of Kubernetes API Conventions. Its author says they had referred to the document repeatedly and found it valuable for understanding the API. That is anecdotal rather than usage telemetry, but it is a concrete signal from a reader of an implementation-facing document.

The likely audience here is not only people onboarding to OpenTelemetry. SDK, instrumentation, exporter, and Collector authors need to check exact data-model and behavior requirements. Users also consult specifications when troubleshooting or comparing implementations. A translation could make the authoritative English text easier to understand and discuss, while remaining non-normative.

I have not found public data that isolates the effect of translated specifications on implementation quality or adoption. These examples do show that implementation-facing API references are localized within a CNCF project, and that at least one reader found a translated API conventions document useful.

[pellared]

BCP 14 keywords such as MUST, SHOULD, and MAY remain in English.

Wouldn't this be strange? Personally, I would propose to create some official mapping for these terms. See https://www.nic.ad.jp/ja/tech/ipa/RFC2119JA.html as an example.

[ymotongpoo]

I agree that keeping the BCP 14 keywords only in English could feel awkward in Japanese. Japanese RFC translations commonly pair the Japanese wording with the original uppercase keyword.

The Japanese translation of RFC 2119 gives the mapping near the beginning—for example, 「しなければならない（MUST）」 and 「してもよい（MAY）」. Other translated RFCs, such as RFC 2979 and RFC 3552, use the same pattern inline.

These examples show an established practice, though not a universal formatting rule. We could include a short BCP 14 mapping near the beginning of each translated page and keep the uppercase keyword visible where it carries a requirement. The mapping should follow RFC 2119/8174 precisely, with a clear notice that the English version remains authoritative.

[ymotongpoo]

I'd like to follow up on this discussion.

@pellared, thank you for raising the concern about translation accuracy and interoperability. I agree that translations can introduce ambiguity, even when we keep MUST, SHOULD, and MAY in English.

The original proposal keeps English as the sole normative specification. The Japanese translations would serve as informative references, with a notice and a link to the English source on each page. The Japanese localization team would maintain them in the website repository.

Could you clarify whether your objection extends to hosting explicitly non-normative translations on opentelemetry.io? Or are there additional safeguards that would make a limited pilot acceptable?

To keep the scope manageable, I suggest we focus on a few pages from the OTel specification, such as the overview and glossary. We can discuss OTLP, semantic conventions, and OpAMP separately. For now, the decision I’m asking for is whether we can explore this limited pilot, with publication details to follow.

Could the spec maintainers or TC help identify who can take this question forward? My APAC timezone makes attending the spec meetings difficult. If someone could bring this to a meeting and share the outcome here, I would appreciate it. I can provide a short written proposal and answer questions asynchronously.

cc: @svrnm