poe-svelte-ui-lib 1.45.0 → 1.46.0

package/README.md

@@ -110,6 +110,8 @@ npm install poe-svelte-ui-lib
 
 **README компонента** (`src/lib/<Компонент>/README.md`, вкладка «Инфо» витрины) — развёрнутая документация для разработчика. Первые разделы повторяют описание (i) и не должны ему противоречить, дальше идут разработческие: `## Назначение` (плюс заметка о размерах) → `## Пакет данных` (плюс `### Протокол устройства` / пример кода прошивки) → `## Ключи` (таблица «Ключ / Описание», те же формулировки, что в (i)) → `## Особенности` (поведение, ограничения) → `## Пропсы` (таблица «Название / Тип / По умолчанию / Описание», колбэки — `### Колбэки`) → `## Примеры` (Svelte) → `## Конструктор свойств (<Компонент>Props.svelte)` → `## Внутреннее устройство`.
 
+**Языки — единственный источник в библиотеке.** Список языков — `LANGUAGES` в `locales/languages.ts` (код и название, без Svelte — годится и для серверного кода); из него выводятся `LanguageCode`, `LANGUAGE_CODES`, `isLanguageCode` и тип строки словаря `Translation` (по переводу на каждый язык в порядке `LANGUAGES`, TypeScript не даст пропустить язык). `locales/i18n.ts` — текущий язык `Language`/`setLanguage` (сохраняется в `localStorage` `AppLanguage`), `LOCALES` для переключателей (с флагами) и механизм перевода `createTranslator(словарь)`. Приложения (DevCloud, WebApp, терминал) свой список языков, хранилище и функцию перевода не держат: берут `Language`, `setLanguage`, `LOCALES` из библиотеки, а свой `$T` строят из своего словаря — `export const T = createTranslator(translations)`, где `translations: Translations`. Одно `setLanguage` переключает и компоненты библиотеки, и приложение. Новый язык — строка в `LANGUAGES` и флаг в `i18n.ts`, затем TypeScript покажет все словари, где не хватает перевода.
+
 **Языки (ru/en/zh) — два слоя:**
 
 - **Встроенные тексты компонентов** (подписи полей виджетов, кнопки, подсказки, `aria-label`) — только через словарь `src/lib/locales/translations.ts` и `$T("ключ")`; строка с числами — параметрами: `$T("widget.fs.files", { n: files.length })` на ключ `"Файлов: {n}"`. Русских литералов в разметке и скриптах компонентов быть не должно. Списки вариантов с подписями — `$derived`, иначе не переключатся при смене языка. Исключение — шкалы прибора `WidgetPFD`: там общепринятые авиационные сокращения (`SPD`, `ALT`, `AS`, `VS`, `NO DATA`) на всех языках, переводятся только подсказки и строки состояния.

package/dist/Input/InputProps.svelte

@@ -3,7 +3,7 @@
   import { getContext } from "svelte"
   import { T } from "../locales/i18n"
   import translations from "../locales/translations"
-  import { LANGUAGE_CODES } from "../locales/localize"
+  import { LANGUAGE_CODES } from "../locales/languages"
   import type { IInputProps, UIComponent, IOption, IUIComponentHandler } from "../types"
   import * as UI from ".."
   import { optionsStore, findColorOption } from "../options"

package/dist/TextsEditor.svelte

@@ -3,8 +3,8 @@
      поэтому окно одно на все компоненты; окна свойств сами тексты не показывают и не правят. -->
 <script lang="ts">
   import { T } from "./locales/i18n"
-  import { LANGUAGE_CODES, collectTexts, packLocalized, setAtPath, type TextPath } from "./locales/localize"
-  import type { LanguageCode } from "./locales/translations"
+  import { collectTexts, packLocalized, setAtPath, type TextPath } from "./locales/localize"
+  import { LANGUAGE_CODES, type LanguageCode } from "./locales/languages"
   import Button from "./Button/Button.svelte"
   import Input from "./Input/Input.svelte"
   import Modal from "./Modal.svelte"

package/dist/index.d.ts

@@ -51,7 +51,7 @@ export { default as WidgetPFDProps } from "./WidgetPFD/WidgetPFDProps.svelte";
 export { default as WidgetMap } from "./WidgetMap/WidgetMap.svelte";
 export { default as WidgetMapProps } from "./WidgetMap/WidgetMapProps.svelte";
 export * from "./locales/i18n";
-export * from "./locales/translations";
+export * from "./locales/languages";
 export * from "./locales/localize";
 export { widgetAccentStyle } from "./widgetAccent";
 export * from "./ModalStackStore";

package/dist/index.js

@@ -52,7 +52,7 @@ export { default as WidgetPFDProps } from "./WidgetPFD/WidgetPFDProps.svelte";
 export { default as WidgetMap } from "./WidgetMap/WidgetMap.svelte";
 export { default as WidgetMapProps } from "./WidgetMap/WidgetMapProps.svelte";
 export * from "./locales/i18n";
-export * from "./locales/translations";
+export * from "./locales/languages";
 export * from "./locales/localize";
 export { widgetAccentStyle } from "./widgetAccent";
 export * from "./ModalStackStore";

package/dist/locales/i18n.d.ts

@@ -1,11 +1,14 @@
 import { type Readable } from "svelte/store";
+import { type LanguageCode, type Translations } from "./languages";
 export declare const Language: import("svelte/store").Writable<string>;
 export declare function setLanguage(newLang: string): void;
 export declare const LOCALES: {
     id: string;
     name: string;
-    value: string;
+    value: LanguageCode;
     component: ConstructorOfATypedSvelteComponent;
 }[];
 export type TranslateParams = Record<string, string | number>;
-export declare const T: Readable<(key: string, params?: TranslateParams) => string>;
+export type Translator = (key: string, params?: TranslateParams) => string;
+export declare const createTranslator: (dictionary: Translations) => Readable<Translator>;
+export declare const T: Readable<Translator>;

package/dist/locales/i18n.js

@@ -1,39 +1,58 @@
-import { derived } from "svelte/store";
-import { writable } from "svelte/store";
+import { derived, writable } from "svelte/store";
 import translations from "./translations";
 import FlagZh from "./FlagZh.svelte";
 import FlagRu from "./FlagRu.svelte";
 import FlagEn from "./FlagEn.svelte";
-/* Язык по умолчанию */
-let initialLanguage = "ru";
-/* Проверяем, доступен ли localStorage */
+import { DEFAULT_LANGUAGE, LANGUAGES, isLanguageCode } from "./languages";
+/* Язык и механизм перевода — общие для библиотеки и приложений: приложение берёт отсюда Language/setLanguage/LOCALES и строит свой $T
+   из своего словаря через createTranslator (см. README «Языки»); переключение языка одним setLanguage меняет и компоненты, и приложение */
+/* Стартовый язык: сохранённый → язык браузера → по умолчанию */
+let initialLanguage = DEFAULT_LANGUAGE;
 if (typeof window !== "undefined") {
-    initialLanguage = localStorage.getItem("AppLanguage") || navigator.language?.split("-")[0]?.toLowerCase() || "ru";
-    const supported = ["ru", "en", "zh"];
-    if (!supported.includes(initialLanguage)) {
-        initialLanguage = "ru";
+    let saved = null;
+    try {
+        saved = localStorage.getItem("AppLanguage");
     }
+    catch {
+        /* хранилище недоступно */
+    }
+    const candidate = saved || navigator.language?.split("-")[0]?.toLowerCase();
+    if (isLanguageCode(candidate))
+        initialLanguage = candidate;
 }
-/* Создаем хранилище с начальным значением языка */
+/* Текущий язык */
 export const Language = writable(initialLanguage);
-/* Функция для изменения языка */
+/* Смена языка с сохранением выбора */
 export function setLanguage(newLang) {
+    if (!isLanguageCode(newLang))
+        return;
     if (typeof window !== "undefined") {
-        localStorage.setItem("AppLanguage", newLang);
+        try {
+            localStorage.setItem("AppLanguage", newLang);
+        }
+        catch {
+            /* хранилище недоступно — выбор действует до перезагрузки */
+        }
     }
     Language.set(newLang);
 }
-/* Поддерживаемые языки (код, название языка, флаг) */
-export const LOCALES = [
-    { id: "app-language-ru", name: "Русский", value: "ru", component: FlagRu },
-    { id: "app-language-en", name: "English", value: "en", component: FlagEn },
-    { id: "app-language-zh", name: "中国人", value: "zh", component: FlagZh },
-];
-/* Индекс языка в кортеже перевода [ru, en, zh] — жёстко привязан к порядку LOCALES */
-const LANGUAGE_INDEX = Object.fromEntries(LOCALES.map((locale, index) => [locale.value, index]));
-/* Функция для перевода для текущего языка */
-function translate(locale, key, params) {
-    const text = translations[key]?.[LANGUAGE_INDEX[locale] ?? 0] || key;
+/* Языки для переключателей: список из languages.ts + флаг */
+const FLAGS = { ru: FlagRu, en: FlagEn, zh: FlagZh };
+export const LOCALES = LANGUAGES.map((language) => ({
+    id: `app-language-${language.value}`,
+    name: language.name,
+    value: language.value,
+    component: FLAGS[language.value],
+}));
+/* Индекс языка в строке словаря — порядок LANGUAGES */
+const LANGUAGE_INDEX = Object.fromEntries(LANGUAGES.map((language, index) => [language.value, index]));
+/* Перевод по словарю: текущий язык → русский → сам ключ */
+const translate = (dictionary, locale, key, params) => {
+    const row = dictionary[key];
+    const text = row?.[LANGUAGE_INDEX[locale] ?? 0] || row?.[0] || key;
     return params ? text.replace(/\{(\w+)\}/g, (match, name) => (name in params ? String(params[name]) : match)) : text;
-}
-export const T = derived(Language, ($lang) => (key, params) => translate($lang, key, params));
+};
+/* $T приложения из его собственного словаря — поверх общего языка */
+export const createTranslator = (dictionary) => derived(Language, ($lang) => (key, params) => translate(dictionary, $lang, key, params));
+/* $T самой библиотеки */
+export const T = createTranslator(translations);

package/dist/locales/languages.d.ts

@@ -0,0 +1,20 @@
+export declare const LANGUAGES: readonly [{
+    readonly value: "ru";
+    readonly name: "Русский";
+}, {
+    readonly value: "en";
+    readonly name: "English";
+}, {
+    readonly value: "zh";
+    readonly name: "中文";
+}];
+export type LanguageCode = (typeof LANGUAGES)[number]["value"];
+export declare const LANGUAGE_CODES: LanguageCode[];
+type StringPerItem<T extends readonly unknown[]> = {
+    -readonly [K in keyof T]: string;
+};
+export type Translation = StringPerItem<typeof LANGUAGES>;
+export type Translations = Record<string, Translation>;
+export declare const DEFAULT_LANGUAGE: LanguageCode;
+export declare const isLanguageCode: (value: unknown) => value is LanguageCode;
+export {};

package/dist/locales/languages.js

@@ -0,0 +1,11 @@
+/* $lib/locales/languages.ts */
+/* Единственный источник списка языков для библиотеки и всех приложений на ней (DevCloud, WebApp, терминал); без Svelte-зависимостей — годится и для серверного кода */
+export const LANGUAGES = [
+    { value: "ru", name: "Русский" },
+    { value: "en", name: "English" },
+    { value: "zh", name: "中文" },
+];
+/* Коды в порядке LANGUAGES — он же порядок переводов в строке словаря */
+export const LANGUAGE_CODES = LANGUAGES.map((language) => language.value);
+export const DEFAULT_LANGUAGE = "ru";
+export const isLanguageCode = (value) => LANGUAGE_CODES.includes(value);

package/dist/locales/localize.d.ts

@@ -1,6 +1,5 @@
-import type { LanguageCode } from "./translations";
+import { type LanguageCode } from "./languages";
 export type LocalizedText = string | Partial<Record<LanguageCode, string>>;
-export declare const LANGUAGE_CODES: LanguageCode[];
 export declare const isLocalizedText: (value: unknown) => value is Partial<Record<LanguageCode, string>>;
 export declare const localizeText: (value: LocalizedText | undefined, lang: string) => string;
 export declare function localizeDeep<T>(value: T, lang: string): T;

package/dist/locales/localize.js

@@ -1,4 +1,6 @@
-export const LANGUAGE_CODES = ["ru", "en", "zh"];
+/* $lib/locales/localize.ts */
+/* Многоязычные тексты, введённые в конструкторе: строка (один язык) или объект { ru, en, zh }; ru — основной и запасной */
+import { LANGUAGE_CODES } from "./languages";
 /* Поля свойств, которые считаются текстом для пользователя — их показывает и правит окно «Тексты и переводы» (TextsEditor) */
 const TEXT_KEYS = new Set([
     "name",

package/dist/locales/translations.d.ts

@@ -1,3 +1,3 @@
-export type LanguageCode = "ru" | "en" | "zh";
-declare const translations: Record<string, [string, string, string]>;
+import type { Translations } from "./languages";
+declare const translations: Translations;
 export default translations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-svelte-ui-lib",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Oleg-Perevyshin/ElementsUI.git"