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

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.