@punica/editor 1.7.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/index.d.ts

@@ -23,6 +23,7 @@
 /// <reference path="punica.module.kernel.tasks.d.ts" />
 /// <reference path="punica.module.extensions.api.d.ts" />
 /// <reference path="punica.module.extensions.settings.d.ts" />
+/// <reference path="punica.module.extensions.i18n.d.ts" />
 /// <reference path="punica.module.runtime.fs.d.ts" />
 /// <reference path="punica.module.runtime.search.d.ts" />
 /// <reference path="punica.module.runtime.vcs.d.ts" />

package/types/punica.module.extensions.api.d.ts

@@ -716,6 +716,16 @@ declare module 'punica' {
        */
       export const manager: extensions.settings.SettingsApi;
     }
+
+    /**
+     * Localization engine for extension user interfaces.
+     */
+    namespace i18n {
+      /**
+       * Localization façade surfaced via `punica.extensions.i18n.manager`.
+       */
+      export const manager: extensions.i18n.I18nApi;
+    }
   }
 
   /**
@@ -809,5 +819,18 @@ declare module 'punica' {
        */
       export const manager: SettingsApi;
     }
+
+    /**
+     * Localization engine — see punica.module.extensions.i18n.d.ts.
+     */
+    export namespace i18n {
+      export import I18nApi = extensions.i18n.I18nApi;
+      export import MessageBundle = extensions.i18n.MessageBundle;
+      export import MessageBundles = extensions.i18n.MessageBundles;
+      /**
+       * Localization façade surfaced via `punica.extensions.i18n.manager`.
+       */
+      export const manager: I18nApi;
+    }
   }
 }

package/types/punica.module.extensions.i18n.d.ts

@@ -0,0 +1,83 @@
+declare module 'punica' {
+  export namespace extensions {
+    /**
+     * Localization for extension user interfaces.
+     *
+     * The substrate owns the ENGINE — one active locale, one change event, one
+     * plural implementation — and extensions own only their dictionaries. The
+     * alternative, a helper copied into every extension, is how this fleet
+     * handles small utilities, but an engine is not a small utility: 80-odd
+     * copies of plural selection and fallback order drift apart, and the drift
+     * shows up as a half-translated screen rather than a failing build.
+     *
+     * The language is stored in the shared `system` / `ui.language` setting,
+     * the same namespace the theme lives in, so every extension resolves the
+     * same value. The set of offered languages comes from the active
+     * ApplicationProfile's `localization.supported` — a v1 slot that existed
+     * unused until this API filled it.
+     */
+    export namespace i18n {
+      /** A dictionary: flat dot-separated keys to display strings. */
+      export type MessageBundle = Record<string, string>;
+
+      /** Locale tag (`en`, `tr`) to that locale's dictionary. */
+      export type MessageBundles = Record<string, MessageBundle>;
+
+      export interface I18nApi {
+        /**
+         * The active locale tag. Resolution order: the `ui.language` setting,
+         * then the app/OS language's subtag when it is supported, then the
+         * profile's declared default, then `'en'`.
+         */
+        getLocale(): string;
+
+        /**
+         * Change the language for the whole application. Writes
+         * `system` / `ui.language` at global scope and notifies subscribers;
+         * callers do not write the setting themselves.
+         */
+        setLocale(locale: string): Promise<void>;
+
+        /**
+         * Languages this product offers, from the active profile's
+         * `localization.supported`. Falls back to `['en']` when the profile
+         * declares none.
+         */
+        supportedLocales(): string[];
+
+        /** Subscribe to language changes. Returns an unsubscribe function. */
+        onDidChange(listener: (locale: string) => void): () => void;
+
+        /**
+         * Register an extension's dictionaries, keyed by locale tag. Call once
+         * during `activate()`, before anything renders. Registering again for
+         * the same extension replaces the previous bundles, so a reload during
+         * development does not accumulate stale strings.
+         */
+        register(extensionName: string, bundles: MessageBundles): void;
+
+        /**
+         * Look up a message for a registered extension.
+         *
+         * `params` values are interpolated into `{name}` placeholders. A
+         * numeric `params.count` also selects a plural form: the lookup tries
+         * `<key>.<pluralCategory>` (via `Intl.PluralRules`) before `<key>`,
+         * which is what lets English say "1 attempt" / "2 attempts" while
+         * Turkish keeps one form after a numeral.
+         *
+         * Never throws. When no message is found — unregistered extension,
+         * unknown key, missing locale — the key itself is returned, because a
+         * visible key is greppable and cannot be mistaken for finished copy.
+         */
+        t(
+          extensionName: string,
+          key: string,
+          params?: Record<string, string | number>
+        ): string;
+      }
+
+      /** Localization façade surfaced via `punica.extensions.i18n.manager`. */
+      export const manager: I18nApi;
+    }
+  }
+}