GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: optional lang/canonical fields for multilingual concepts

Open
#49 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Summary

Add two optional frontmatter fields — `lang` and `canonical` — so a bundle can
carry the same concept in more than one language. Purely additive: no MUST
changes, no impact on existing bundles or consumers.

## Motivation

OKF v0.1 has no notion of language. In practice many bundles are authored for a
mixed audience (e.g. an English source repo documented for a Chinese-speaking
team, or a glossary that needs both). Today there is no agreed way to say "this
document is the Chinese version of that concept", so producers either pick one
language and lose the other, or ship two documents that consumers see as two
unrelated concepts.

Because the spec already encourages producers to add their own keys (§4.1) and
already requires consumers to tolerate unknown ones (§4.1, §9), the only thing
missing is a *shared name* for these two fields so that different producers and
consumers agree.

## Proposal

Two optional frontmatter fields:

- `lang` — a BCP 47 language tag (`en`, `zh`, `zh-Hans`, …) for the language of
the document body. Absent = language not declared.
- `canonical` — the concept ID of the primary-language version. Translations
point at a shared canonical concept, so language variants can be grouped as
one logical concept.

File layout is left to the producer; two common conventions:

- parallel files — `tables/orders.md` and `tables/orders.zh.md`
- parallel directories — `en/tables/orders.md` and `zh/tables/orders.md`

Language-aware consumers SHOULD treat documents sharing a `canonical` as one
concept and pick a variant by `lang`. Consumers that don't understand the
fields keep treating each document as an independent concept — the bundle stays
conformant either way.

## Backward compatibility

- No MUST is changed; both fields are optional.
- Unknown to a v0.1 consumer → ignored per the existing unknown-key rule (§4.1,
§9). Existing bundles are unaffected.
- This is a backward-compatible minor-version addition under §11.

## Reference implementation

We've been using exactly these two fields in a community toolset (producers for
Feishu / Obsidian / Notion / GitHub / HTML, all emitting `lang`, with
`canonical` linking translations and originals):
https://github.com/yzfly/awesome-okf

## Open questions for maintainers

1. Field names — is `canonical` clear, or would you prefer something like
`translation_of` / `same_as`?
2. Should the spec bless one file-naming convention (`..md`), or leave
layout entirely to producers as proposed here?
3. Any interest in a matching note in §6 (index) for per-language listings?

Happy to send a PR against `okf/SPEC.md` (draft diff ready) once there's a
direction you're comfortable with.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.