@origingame/engine 0.0.0-stage → 0.1.0

package/knowledge/wiki/i18n.md

@@ -0,0 +1,213 @@
+<!-- Generated from crates/og-api/api.ogt by `og api gen`. Do not edit: `og api check` fails on any difference; change api.ogt and regenerate. -->
+
+# The `i18n` module
+
+Localization: one string table per locale (`.ogt` of `type strings`: `locale "ja"`, its font chain `fonts "..."`, `string "key" "message"`), messages in a subset of ICU MessageFormat (`{name}`, `{n, number}`, `{n, plural, =0 {..} one {..} other {..}}` with `#`, `{g, select, a {..} other {..}}`), CLDR plural rules, and the locale the host asks for (the browser's `navigator.language` on the web, `og run --locale` natively).
+
+The active locale is the best loaded table for the request (ja-JP takes ja; zh-TW takes zh-Hant or zh-TW), else the base table (`base true`, else en, else the first). A key it lacks is read from its `fallback` table, then the base. It also sets the UI's font chain (its fonts first, then the other tables') and direction: a right-to-left locale (ar, he, fa, ur) mirrors og.ui's layout, and og-ui shapes Arabic words with the font's own tables (a font cooked with the `arabic` charset carries them). `og cook` warns about every key a locale lacks, or takes other arguments for, than the base.
+
+- **TypeScript**: functions are the namespace `og.i18n`; components, resources and events are tokens on `og`.
+- **Publish builds**: kept (members may override).
+- **Skill**: `og-i18n`, which teaches the module (how much of it to use, and how to prove it).
+- **Index**: [every module and name](index.md).
+
+```ogt
+module i18n {
+  # declarations follow, each quoted below
+```
+
+<sub>`api.ogt` line 7718</sub>
+
+## Contents
+
+| Name | Kind | Summary |
+|---|---|---|
+| [`LocaleInfo`](#type-LocaleInfo) | struct | The localization state. |
+| [`og.i18n.load`](#fn-load) | function | Load a cooked string table; the active locale is negotiated again. |
+| [`og.i18n.setLocale`](#fn-setLocale) | function | Ask for a locale (a player's choice in settings); the active one is the best table for it. |
+| [`og.i18n.locale`](#fn-locale) | function | The requested and active locales, the direction and the font chain. |
+| [`og.i18n.t`](#fn-t) | function | A key's message in the active locale, formatted with its arguments; a key no table has answers the key itself and logs one warning. |
+| [`og.i18n.has`](#fn-has) | function | Whether the active locale's own table has the key (not a fallback). |
+
+## Functions
+
+<a id="fn-load"></a>
+
+### `og.i18n.load`
+
+Load a cooked string table; the active locale is negotiated again.
+
+```ts
+og.i18n.load(world: World, path: string): Result<LocaleInfo>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `path` | `string` | no | The table, such as `strings/ja.ogt`. |
+
+**Returns** `Result<LocaleInfo>`: Refused for a path that is not a cooked string table, or a font of its chain that is not cooked.
+
+Binding symbol `og_i18n_load` · publish builds: kept
+
+```ogt
+fn load {
+  doc "Load a cooked string table; the active locale is negotiated again."
+  param world World "The world."
+  param path String "The table, such as `strings/ja.ogt`."
+  returns Result.LocaleInfo "Refused for a path that is not a cooked string table, or a font of its chain that is not cooked."
+}
+```
+
+<sub>`api.ogt` line 7732</sub>
+
+<a id="fn-setLocale"></a>
+
+### `og.i18n.setLocale`
+
+Ask for a locale (a player's choice in settings); the active one is the best table for it.
+
+```ts
+og.i18n.setLocale(world: World, locale: string): LocaleInfo
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `locale` | `string` | no | A BCP 47 tag: `ja`, `zh-CN`, `ar-EG`. |
+
+**Returns** `LocaleInfo`.
+
+Binding symbol `og_i18n_set_locale` · publish builds: kept
+
+```ogt
+fn setLocale {
+  doc "Ask for a locale (a player's choice in settings); the active one is the best table for it."
+  param world World "The world."
+  param locale String "A BCP 47 tag: `ja`, `zh-CN`, `ar-EG`."
+  returns LocaleInfo
+}
+```
+
+<sub>`api.ogt` line 7739</sub>
+
+<a id="fn-locale"></a>
+
+### `og.i18n.locale`
+
+The requested and active locales, the direction and the font chain.
+
+```ts
+og.i18n.locale(world: World): LocaleInfo
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+**Returns** `LocaleInfo`.
+
+Binding symbol `og_i18n_locale` · publish builds: kept
+
+```ogt
+fn locale {
+  doc "The requested and active locales, the direction and the font chain."
+  param world World "The world."
+  returns LocaleInfo
+}
+```
+
+<sub>`api.ogt` line 7746</sub>
+
+<a id="fn-t"></a>
+
+### `og.i18n.t`
+
+A key's message in the active locale, formatted with its arguments; a key no table has answers the key itself and logs one warning.
+
+```ts
+og.i18n.t(world: World, key: string, args?: unknown): string
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `key` | `string` | no | The key, such as `menu.start`. |
+| `args` | `unknown` | yes | The arguments: an object of strings and numbers, `{ count: 3, name: "Kai" }`. |
+
+**Returns** `string`.
+
+Binding symbol `og_i18n_t` · publish builds: kept
+
+```ogt
+fn t {
+  doc "A key's message in the active locale, formatted with its arguments; a key no table has answers the key itself and logs one warning."
+  param world World "The world."
+  param key String "The key, such as `menu.start`."
+  param args Json "The arguments: an object of strings and numbers, `{ count: 3, name: \"Kai\" }`." {
+    optional true
+  }
+  returns String
+}
+```
+
+<sub>`api.ogt` line 7752</sub>
+
+<a id="fn-has"></a>
+
+### `og.i18n.has`
+
+Whether the active locale's own table has the key (not a fallback).
+
+```ts
+og.i18n.has(world: World, key: string): boolean
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `key` | `string` | no | The key. |
+
+**Returns** `boolean`.
+
+Binding symbol `og_i18n_has` · publish builds: kept
+
+```ogt
+fn has {
+  doc "Whether the active locale's own table has the key (not a fallback)."
+  param world World "The world."
+  param key String "The key."
+  returns bool
+}
+```
+
+<sub>`api.ogt` line 7762</sub>
+
+## Types
+
+<a id="type-LocaleInfo"></a>
+
+### `LocaleInfo` (struct)
+
+The localization state.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `requested` | `string` | `""` | — | — | — | The locale the host or the game asked for (empty: none). |
+| `active` | `string` | `""` | — | — | — | The table in use (empty: none loaded). |
+| `direction` | `string` | `""` | — | — | — | `ltr` or `rtl`. |
+| `locales` | `readonly string[]` | `[]` | — | — | — | Every loaded table's locale. |
+| `fonts` | `readonly string[]` | `[]` | — | — | — | The UI's font chain, first first. |
+
+```ogt
+struct LocaleInfo {
+  doc "The localization state."
+  field requested String "The locale the host or the game asked for (empty: none)."
+  field active String "The table in use (empty: none loaded)."
+  field direction String "`ltr` or `rtl`."
+  field locales List.String "Every loaded table's locale."
+  field fonts List.String "The UI's font chain, first first."
+}
+```
+
+<sub>`api.ogt` line 7723</sub>