Files
pages/docs/design/i18n-delivery.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
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.
2026-09-27 14:44:43 +09:00

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.