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.
396 lines
4.9 KiB
Markdown
396 lines
4.9 KiB
Markdown
# Language Projection Draft
|
|
|
|
## Goal
|
|
|
|
Language should NOT affect semantic hierarchy.
|
|
|
|
Language is treated as:
|
|
|
|
```text
|
|
projection
|
|
representation
|
|
view
|
|
```
|
|
|
|
rather than containment.
|
|
|
|
* * *
|
|
|
|
# Core Philosophy
|
|
|
|
## URL hierarchy is language-neutral
|
|
|
|
Paths represent:
|
|
|
|
```text
|
|
semantic location
|
|
knowledge locality
|
|
human navigation
|
|
```
|
|
|
|
NOT language ownership.
|
|
|
|
* * *
|
|
|
|
# Example
|
|
|
|
Preferred:
|
|
|
|
```text
|
|
/dev/api/auth
|
|
```
|
|
|
|
Avoid:
|
|
|
|
```text
|
|
/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.
|
|
|
|
```text
|
|
Page UUID
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
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
|
|
|
|
```http
|
|
GET /dev/api/auth
|
|
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
|
|
```
|
|
|
|
* * *
|
|
|
|
# Resolution Flow
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
default_lang = ja
|
|
allowed_langs = ja,en
|
|
```
|
|
|
|
* * *
|
|
|
|
# Global campus
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/_/lang/ja/dev/api/auth
|
|
```
|
|
|
|
However:
|
|
|
|
```text
|
|
this is NOT canonical
|
|
```
|
|
|
|
* * *
|
|
|
|
# Why This Design
|
|
|
|
## Prevents hierarchy pollution
|
|
|
|
Avoids:
|
|
|
|
```text
|
|
language hierarchy
|
|
```
|
|
|
|
overwriting:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
path != object
|
|
```
|
|
|
|
and extends it into:
|
|
|
|
```text
|
|
representation != object
|
|
```
|
|
|
|
* * *
|
|
|
|
# Conceptual Mapping
|
|
|
|
Concept Meaning Path semantic locator UUID identity Revision representation Language projection
|
|
|
|
* * *
|
|
|
|
# NDN-like Interpretation
|
|
|
|
## Name
|
|
|
|
```text
|
|
/dev/api/auth
|
|
```
|
|
|
|
semantic and language-neutral.
|
|
|
|
* * *
|
|
|
|
## Content Negotiation
|
|
|
|
Language selection behaves similarly to:
|
|
|
|
```text
|
|
content negotiation
|
|
```
|
|
|
|
using:
|
|
|
|
```text
|
|
Accept-Language
|
|
```
|
|
|
|
* * *
|
|
|
|
# UI Philosophy
|
|
|
|
Language switching should feel lightweight.
|
|
|
|
Example UI:
|
|
|
|
```text
|
|
[Japanese] [English] [中文]
|
|
```
|
|
|
|
without changing semantic location.
|
|
|
|
* * *
|
|
|
|
# Important Principle
|
|
|
|
Language should not fork the knowledge universe.
|
|
|
|
Avoid:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
projection
|
|
representation
|
|
view
|
|
```
|
|
|
|
NOT:
|
|
|
|
```text
|
|
ownership
|
|
containment
|
|
hierarchy
|
|
```
|
|
|
|
This preserves semantic structure while supporting multilingual knowledge naturally.
|