Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
4.9 KiB
Language Projection Draft
Goal
Language should NOT affect semantic hierarchy.
Language is treated as:
projection
representation
view
rather than containment.
Core Philosophy
URL hierarchy is language-neutral
Paths represent:
semantic location
knowledge locality
human navigation
NOT language ownership.
Example
Preferred:
/dev/api/auth
Avoid:
/ja/dev/api/auth
/en/dev/api/auth
because language hierarchy pollutes semantic hierarchy.
Important Separation
Layer Meaning Path semantic hierarchy Page UUID identity Revision representation Language projection
Internal Model
Page
Language-neutral semantic object.
Page UUID
Example:
Page
├─ Japanese revision
├─ English revision
└─ Chinese revision
Revision
Language-specific content snapshot.
revisions table
| Field | Meaning |
|---|---|
uuid |
Immutable Revision UUID |
object_uuid |
Parent Page UUID; retained name during the Object-to-Page migration |
document_hash |
SHA-256 of the immutable canonical payload |
lang |
Canonical BCP 47 language tag or und |
message |
Commit message |
created_at_ms |
Unix epoch milliseconds |
The payload is addressed by document_hash; it is not identified by the
Revision UUID.
Language Resolution
Request
GET /dev/api/auth
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
Resolution Flow
Page UUID
↓
find latest revision(lang=ja-JP)
↓ not found
find latest revision(lang=ja)
↓ not found
find latest revision(lang=en)
↓ not found
find latest revision(lang=campus default)
↓ not found
find latest revision(lang=system default)
↓ not found
find latest revision(lang=und)
Fallback Philosophy
Language fallback is preferred over URL duplication.
Recommended Fallback Chain
Example:
ja-JP
↓
ja
↓
campus default
↓
system default
↓
und
Duplicate candidates are removed while preserving order. Invalid language
tags are ignored. und is the compatibility projection for revisions created
before language-aware delivery.
Zone Language Metadata
Zones may optionally define language affinity.
zones
| Field | Meaning |
|---|---|
default_lang |
Preferred fallback language |
allowed_langs |
Allowed languages |
Example
JP-oriented campus
default_lang = ja
allowed_langs = ja,en
Global campus
default_lang = en
allowed_langs = *
Spot Language Metadata
Spot may optionally specify:
| Field | Meaning |
|---|---|
preferred_lang |
Preferred rendering language |
This influences rendering preference only.
It does NOT change identity.
Canonical URL Policy
Canonical URL remains language-neutral.
Example:
/dev/api/auth
Language selection is handled at rendering time.
Optional Explicit Language URL
Explicit language paths may exist for:
- debugging
- preview
- direct linking
- translators
Example:
/_/lang/ja/dev/api/auth
However:
this is NOT canonical
Why This Design
Prevents hierarchy pollution
Avoids:
language hierarchy
overwriting:
semantic hierarchy
Benefits
1. Stable semantic URLs
The same knowledge object keeps the same path.
2. Shared semantic identity
Multiple languages refer to the same:
Page UUID
3. Better multitree behavior
Aliases and bindings remain language-neutral.
4. Better graph compatibility
Semantic relations do not duplicate per-language.
Relation to Existing Architecture
This design aligns with:
path != object
and extends it into:
representation != object
Conceptual Mapping
Concept Meaning Path semantic locator UUID identity Revision representation Language projection
NDN-like Interpretation
Name
/dev/api/auth
semantic and language-neutral.
Content Negotiation
Language selection behaves similarly to:
content negotiation
using:
Accept-Language
UI Philosophy
Language switching should feel lightweight.
Example UI:
[Japanese] [English] [中文]
without changing semantic location.
Important Principle
Language should not fork the knowledge universe.
Avoid:
ja-wiki
en-wiki
style silo fragmentation unless intentionally desired.
Current Recommended Direction
Layer Model UI semantic hierarchy URL language-neutral Internal revision projection Identity UUID Rendering Accept-Language + fallback
Summary
Language is treated as:
projection
representation
view
NOT:
ownership
containment
hierarchy
This preserves semantic structure while supporting multilingual knowledge naturally.