@aethervtt/shard-text 0.0.1

package/dist/locale.d.ts

@@ -0,0 +1,133 @@
+import { AssetStore, type ImporterDef } from '@aethervtt/shard-assets';
+import { type ComponentDef, type Query, ShardError, type World } from '@aethervtt/shard-core';
+import { type App, type AppMethod } from '@aethervtt/shard-runtime';
+export declare const PLURAL_CATEGORIES: readonly ['zero', 'one', 'two', 'few', 'many', 'other'];
+export type PluralCategory = (typeof PLURAL_CATEGORIES)[number];
+/** One string: plain, or by plural category (`{ "one": "{n} item", "other": "{n} items" }`). */
+export type StringEntry = string | Partial<Record<PluralCategory, string>>;
+/** A loaded `*.strings.json`: key → string for one locale. Hot reload bumps `version`. */
+export declare class StringTable {
+    locale: string;
+    strings: Map<string, StringEntry>;
+    version: number;
+    constructor(locale: string, strings: Map<string, StringEntry>);
+    copyFrom(other: StringTable): void;
+}
+export declare const StringTables: import("@aethervtt/shard-core").ResourceDef<AssetStore<StringTable, "StringTable">>;
+export declare const StringTableAssetType: import("@aethervtt/shard-assets").AssetTypeDef<StringTable>;
+/**
+ * The locale a table's file name names: `en.strings.json` and `hud.pt-BR.strings.json` are `en`
+ * and `pt-BR`. Undefined if the name has no valid BCP 47 tag.
+ */
+export declare function localeOfPath(path: string): string | undefined;
+/** The `{name}` placeholders in an entry, sorted and deduplicated. */
+export declare function placeholdersOf(entry: StringEntry): string[];
+/** Every problem in a string table's JSON, each with a JSON pointer. */
+export declare function validateStringTable(json: unknown): ShardError[];
+/** `*.strings.json`: one locale's strings, named by the locale (`locales/pt-BR.strings.json`). */
+export declare const StringTableImporter: ImporterDef;
+export declare const stringTableSchema: () => unknown;
+export interface LocaleValue {
+    /** BCP 47 tag, e.g. `pt-BR`. */
+    current: string;
+    /** The last locale tried: `pt-BR` falls back to `pt`, then this. */
+    fallback: string;
+}
+export declare const Locale: import("@aethervtt/shard-core").ResourceDef<LocaleValue>;
+/** The locales tried for `current`, in order: `pt-BR` → `pt` → `en`. */
+export declare function localeChain(current: string, fallback: string): string[];
+interface Merged {
+    /** Key → entry, over every loaded table of the locale. */
+    strings: Map<string, StringEntry>;
+    /** Key → the table it came from, for validation messages. */
+    source: Map<string, string>;
+}
+/** Localization state for one world: merged tables, formatters, and what failed to resolve. */
+export declare class LocaleStore {
+    /** Bumped when a string table loads, changes, or goes away. */
+    revision: number;
+    /** The chain tried for the current locale. */
+    chain: string[];
+    /** Bumped when the chain changes (the locale was switched). */
+    chainRevision: number;
+    private chainFor;
+    private merged;
+    private readonly plurals;
+    private readonly numbers;
+    /** Keys requested at runtime that no locale in the chain had, by locale. */
+    readonly missing: Map<string, Set<string>>;
+    /** Components whose `key` and `params` fields localize (UiText, Text, ScreenText). */
+    readonly targets: {
+        def: ComponentDef;
+        query: Query | undefined;
+    }[];
+    /** The resolved string's locale after `resolve` ('' if the key was missing). */
+    resolvedLocale: string;
+    /** Recomputes the chain if the locale changed. True if it did. */
+    sync(locale: LocaleValue): boolean;
+    /** Every loaded table's strings, merged per locale (rebuilt after a table changes). */
+    tables(world: World): Map<string, Merged>;
+    invalidate(): void;
+    /**
+     * The string for `key` in the first locale of the chain that has it, formatted with `params`.
+     * Undefined if none has it (the miss is recorded and logged once).
+     */
+    resolve(world: World, key: string, params: unknown): string | undefined;
+    /** Formats one entry: picks the plural form, then fills `{name}` placeholders. */
+    format(entry: StringEntry, locale: string, params: unknown): string;
+    pluralRules(locale: string): Intl.PluralRules;
+    numberFormat(locale: string): Intl.NumberFormat;
+}
+export declare const LocaleState: import("@aethervtt/shard-core").ResourceDef<LocaleStore>;
+/**
+ * The string for `key` in the current locale: `tr(world, 'hud.fuel', { amount: 42 })`. Falls back
+ * along `pt-BR` → `pt` → `en`; plural entries pick their form from `n` (or `count`) with
+ * `Intl.PluralRules`, and numbers format with `Intl.NumberFormat`. A missing key returns the key
+ * itself (and logs `locale/missing-key` once).
+ */
+export declare function tr(world: World, key: string, params?: Record<string, unknown>): string;
+/** Switches the locale; keyed text updates on the next frame. */
+export declare function setLocale(world: World, locale: string): void;
+/**
+ * Makes a component's `key` and `params` fields localize: its entities get `text/Localized` with
+ * the resolved string. Text, ScreenText, and UiText are registered by their plugins.
+ */
+export declare function localizeComponent(world: World, def: ComponentDef): void;
+/** Resolves localized keys into `text/Localized`: only rows whose text changed, unless the locale or a table did. */
+export declare const localizeText: import("@aethervtt/shard-core").SystemDef<{
+    revision: number;
+    chain: number;
+}>;
+/** Components that carry localization keys, by name (for scanning files without the classes). */
+export declare const KEYED_COMPONENTS: readonly ['ui/UiText', 'text/Text', 'text/ScreenText'];
+/** Keys used in a scene or prefab file: every keyed component's `key`, with its JSON pointer. */
+export declare function localizationKeysIn(json: unknown): {
+    key: string;
+    path: string;
+}[];
+export interface LocalizationReport {
+    /** Locales with at least one table. */
+    locales: string[];
+    /** Every key some table defines. */
+    keys: Set<string>;
+    /** Missing keys and placeholder mismatches, each with the table it concerns. */
+    errors: {
+        source: string;
+        error: ShardError;
+    }[];
+}
+/**
+ * Checks the project's string tables against each other: a key one locale defines and another
+ * lacks (`locale/missing-key`), and a key whose `{placeholders}` differ between locales
+ * (`locale/param-mismatch`). Loads every table in the catalog.
+ */
+export declare function validateLocalization(world: World): Promise<LocalizationReport>;
+export declare const localeMethods: AppMethod[];
+/**
+ * Localization for an app (idempotent): the Locale resource, string tables, the resolving system,
+ * and the locale protocol methods. The text and UI plugins install it.
+ */
+export declare function installLocalization(app: App): void;
+/** Requests every string table in the catalog (small files: all locales stay loaded). */
+export declare function loadStringTables(world: World): Promise<void>;
+export {};