|
1 | | -# LOL i18n Service — ABI/FFI/API V-Triple Documentation |
| 1 | +# LOL i18n Service — ABI/FFI/API Triple Documentation |
2 | 2 |
|
3 | 3 | ## Overview |
4 | 4 |
|
5 | | -The LOL (Language of Languages) i18n service follows the **Hyperpolymath V-Triple Standard**: |
| 5 | +The LOL (Language of Languages) i18n service follows the **Hyperpolymath ABI/FFI/API Triple Standard**: |
6 | 6 |
|
7 | 7 | - **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs |
8 | 8 | - **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility |
9 | | -- **API** exposed in **V-lang** for idiomatic high-level access |
| 9 | +- **API** exposed via a **Zig** gateway (REST/gRPC/GraphQL) for idiomatic high-level access |
10 | 10 |
|
11 | 11 | LOL is always called as a service, never embedded. Consumers initialise with |
12 | 12 | `lol_init()`, perform translation lookups and plural form selection across |
13 | 13 | 1500+ languages, then clean up with `lol_free()`. |
14 | 14 |
|
| 15 | +> **Note:** V-lang was the previous API layer and was banned estate-wide on 2026-04-10. |
| 16 | +> The sidelined V-lang wrappers under `api/v-lol/` and `api/v-gateway/` remain only |
| 17 | +> for historical reference. See their respective `MIGRATION.adoc` files for details. |
| 18 | +
|
15 | 19 | ## Architecture |
16 | 20 |
|
17 | 21 | ``` |
@@ -53,12 +57,17 @@ LOL is always called as a service, never embedded. Consumers initialise with |
53 | 57 | │ linked by (-llol) |
54 | 58 | ▼ |
55 | 59 | ┌─────────────────────────────────────────────────┐ |
56 | | -│ V-lang API (idiomatic wrapper) │ |
57 | | -│ api/v-lol/src/ │ |
58 | | -│ - lol.v (Service struct, public methods) │ |
59 | | -│ - ffi.v (Raw C bindings) │ |
60 | | -│ - types.v (V types: Locale, PluralCategory, │ |
61 | | -│ TranslationResult, LanguageInfo) │ |
| 60 | +│ Zig API Gateway (REST/gRPC/GraphQL) │ |
| 61 | +│ api/zig-gateway/src/ │ |
| 62 | +│ - main.zig (HTTP gateway, triple endpoints,│ |
| 63 | +│ REST 7800 / gRPC 7801 / GQL │ |
| 64 | +│ 7802; REST+gRPC+GraphQL │ |
| 65 | +│ handlers; domain I/O) │ |
| 66 | +│ - types.zig (public domain types; replaces │ |
| 67 | +│ v-lol/src/types.v) │ |
| 68 | +│ - lol_ffi.zig (Zig wrapper around liblol; │ |
| 69 | +│ replaces v-lol/src/lol.v + │ |
| 70 | +│ ffi.v) │ |
62 | 71 | └─────────────────────────────────────────────────┘ |
63 | 72 | ``` |
64 | 73 |
|
|
89 | 98 | │ └── abi/ |
90 | 99 | │ └── lol.h # Auto-generated C header |
91 | 100 | ├── api/ |
92 | | -│ ├── v-lol/ # V-lang API wrapper |
93 | | -│ │ ├── v.mod # V module definition |
| 101 | +│ ├── zig-gateway/ # Canonical API gateway (REST/gRPC/GraphQL) |
| 102 | +│ │ ├── build.zig # Build configuration (links liblol) |
| 103 | +│ │ └── src/ |
| 104 | +│ │ ├── main.zig # HTTP gateway: REST/gRPC/GraphQL handlers + domain I/O |
| 105 | +│ │ ├── types.zig # Public domain types (replaces v-lol/src/types.v) |
| 106 | +│ │ └── lol_ffi.zig # Zig liblol wrapper (replaces v-lol/src/lol.v + ffi.v) |
| 107 | +│ ├── v-lol/ # DEPRECATED — see MIGRATION.adoc |
| 108 | +│ │ ├── v.mod |
94 | 109 | │ │ └── src/ |
95 | | -│ │ ├── lol.v # Public API (Service struct) |
96 | | -│ │ ├── ffi.v # Raw C bindings |
97 | | -│ │ └── types.v # V types and enums |
98 | | -│ └── v-gateway/ # Existing triple API gateway |
99 | | -│ └── src/ # REST + gRPC + GraphQL |
| 110 | +│ └── v-gateway/ # DEPRECATED — see MIGRATION.adoc |
| 111 | +│ └── src/ |
100 | 112 | └── ABI-FFI-README.md # This file |
101 | 113 | ``` |
102 | 114 |
|
103 | 115 | ## Key Types |
104 | 116 |
|
105 | | -| Type | Idris2 | C | V | |
106 | | -|------|--------|---|---| |
107 | | -| Result codes | `Result` | `lol_result_t` | `LolError` | |
108 | | -| Plural category | `PluralCategory` | `lol_plural_category_t` | `PluralCategory` | |
109 | | -| Locale | `Locale` | `lol_locale_t` | `Locale` | |
110 | | -| Translation | `TranslationResult` | `lol_translation_result_t` | `TranslationResult` | |
111 | | -| Language info | `LanguageInfo` | `lol_language_info_t` | `LanguageInfo` | |
112 | | -| Plural rule | `PluralRule` | `lol_plural_rule_t` | `PluralRule` | |
| 117 | +| Type | Idris2 | C | |
| 118 | +|------|--------|---| |
| 119 | +| Result codes | `Result` | `lol_result_t` | |
| 120 | +| Plural category | `PluralCategory` | `lol_plural_category_t` | |
| 121 | +| Locale | `Locale` | `lol_locale_t` | |
| 122 | +| Translation | `TranslationResult` | `lol_translation_result_t` | |
| 123 | +| Language info | `LanguageInfo` | `lol_language_info_t` | |
| 124 | +| Plural rule | `PluralRule` | `lol_plural_rule_t` | |
113 | 125 |
|
114 | 126 | ## Formal Proofs (Idris2 ABI) |
115 | 127 |
|
@@ -148,42 +160,39 @@ zig build test # Runs unit tests |
148 | 160 | zig build test-integration # Runs integration tests |
149 | 161 | ``` |
150 | 162 |
|
151 | | -### V-lang API |
| 163 | +### Zig API Gateway |
152 | 164 |
|
153 | 165 | ```bash |
154 | | -cd api/v-lol |
155 | | -v -cflags "-L../../ffi/zig/zig-out/lib" src/ # Build with liblol |
| 166 | +cd api/zig-gateway |
| 167 | +zig build |
| 168 | +./zig-out/bin/lol-gateway |
156 | 169 | ``` |
157 | 170 |
|
158 | | -## Usage (V-lang) |
| 171 | +Default base port is 7800. Configure via `LOL_PORT` environment variable. |
| 172 | +Corpus data directory defaults to `corpus`; set via `LOL_DATA_DIR`. |
159 | 173 |
|
160 | | -```v |
161 | | -import lol |
| 174 | +## Usage (Zig gateway, HTTP) |
162 | 175 |
|
163 | | -fn main() { |
164 | | - // Open the service with a corpus data directory |
165 | | - mut svc := lol.open('/path/to/corpus') or { panic(err) } |
166 | | - defer svc.close() |
| 176 | +The Zig API gateway exposes three endpoint families: |
167 | 177 |
|
168 | | - // Translate a key |
169 | | - result := svc.translate('en-US', 'app.greeting') or { |
170 | | - println('Translation not found, using default') |
171 | | - lol.TranslationResult{ text: 'Hello!', resolved_locale: 'en' } |
172 | | - } |
173 | | - println(result.text) |
174 | | -
|
175 | | - // Select plural form |
176 | | - cat := svc.select_plural('ar', 5) |
177 | | - println('Arabic plural for 5: ${cat}') // "few" |
| 178 | +**REST API** (HTTP on port 7800): |
| 179 | +```bash |
| 180 | +curl http://localhost:7800/api/v1/languages |
| 181 | +curl http://localhost:7800/api/v1/corpus/stats |
| 182 | +``` |
178 | 183 |
|
179 | | - // Get language metadata |
180 | | - info := svc.get_language('eng') or { panic(err) } |
181 | | - println('${info.name} (${info.native_name}): ${info.verse_count} verses') |
| 184 | +**gRPC JSON-compatible** (on port 7801): |
| 185 | +```bash |
| 186 | +curl -X POST http://localhost:7801/lol.TranslationService/Translate \ |
| 187 | + -H "Content-Type: application/json" \ |
| 188 | + -d '{"locale":"en-US","key":"app.greeting"}' |
| 189 | +``` |
182 | 190 |
|
183 | | - // Get plural rule |
184 | | - rule := svc.get_plural_rule('ru') or { panic(err) } |
185 | | - println('Russian has ${rule.form_count} plural forms') |
186 | | -} |
| 191 | +**GraphQL** (on port 7802, endpoint `/graphql`): |
| 192 | +```bash |
| 193 | +curl -X POST http://localhost:7802/graphql \ |
| 194 | + -H "Content-Type: application/json" \ |
| 195 | + -d '{"query":"{ languages { code name } }"}' |
187 | 196 | ``` |
188 | 197 |
|
189 | 198 | ## License |
|
0 commit comments