poe-svelte-ui-lib 1.47.0 → 1.48.0

package/README.md

@@ -110,7 +110,7 @@ npm install poe-svelte-ui-lib
 
 **README компонента** (`src/lib/<Компонент>/README.md`, вкладка «Инфо» витрины) — развёрнутая документация для разработчика. Первые разделы повторяют описание (i) и не должны ему противоречить, дальше идут разработческие: `## Назначение` (плюс заметка о размерах) → `## Пакет данных` (плюс `### Протокол устройства` / пример кода прошивки) → `## Ключи` (таблица «Ключ / Описание», те же формулировки, что в (i)) → `## Особенности` (поведение, ограничения) → `## Пропсы` (таблица «Название / Тип / По умолчанию / Описание», колбэки — `### Колбэки`) → `## Примеры` (Svelte) → `## Конструктор свойств (<Компонент>Props.svelte)` → `## Внутреннее устройство`.
 
-**Языки — единственный источник в библиотеке.** Список языков — `LANGUAGES` в `locales/languages.ts`: код, название и флаг (SVG-строка), без Svelte — годится и для серверного кода. **Новый язык — одна запись в `LANGUAGES`**: переключатели языка во всех приложениях (`LOCALES`), колонки окна «Тексты и переводы», многоязычные тексты GUI и словари подхватывают его сами; пока перевода нет — показывается текст языка по умолчанию (`DEFAULT_LANGUAGE`, `ru`). Словари (`Translations`) — строки-объекты по кодам `{ ru: "…", en: "…", zh: "…" }`: обязателен только язык по умолчанию, порядок не важен; недостающие переводы показывает `findMissingTranslations(словарь)`. `locales/i18n.ts` — текущий язык `Language`/`setLanguage` (неизвестный код не применяется, выбор сохраняется в `localStorage` `AppLanguage`), `restoreLanguage()` (сохранённый или язык браузера; стартовое значение всегда язык по умолчанию — серверный рендер совпадает с гидратацией, поэтому SSR-приложения вызывают его в `onMount` корневого layout, SPA — при старте), `LOCALES` (с флагом `flag`) и механизм перевода `createTranslator(словарь)`. Приложения (DevCloud, WebApp, терминал) свой список языков, хранилище и функцию перевода не держат: берут их из библиотеки и строят свой `$T` из своего словаря — `export const T = createTranslator(translations)`. Одно `setLanguage` переключает и компоненты библиотеки, и приложение. Многоязычные тексты GUI распознаются по виду ключей (коды языков), поэтому данные с языком, убранным из списка, не ломаются.
+**Языки — единственный источник в библиотеке.** Список языков — `LANGUAGES` в `locales/languages.ts`: код, название и флаг (SVG-строка), без Svelte — годится и для серверного кода. **Новый язык — одна запись в `LANGUAGES`**: переключатели языка во всех приложениях (`LOCALES`), колонки окна «Тексты и переводы», многоязычные тексты GUI и словари подхватывают его сами; пока перевода нет — показывается текст языка по умолчанию (`DEFAULT_LANGUAGE`, `ru`). Словари (`Translations`) — строки-объекты по кодам `{ ru: "…", en: "…", zh: "…" }`: обязателен только язык по умолчанию, порядок не важен; недостающие переводы показывает `findMissingTranslations(словарь)`. `locales/i18n.ts` — текущий язык `Language`/`setLanguage` (неизвестный код не применяется, выбор сохраняется в `localStorage` `AppLanguage`), `restoreLanguage()` (сохранённый или язык браузера; стартовое значение всегда язык по умолчанию — серверный рендер совпадает с гидратацией, поэтому SSR-приложения вызывают его в `onMount` корневого layout, SPA — при старте), `LOCALES` (с флагом `flag`) и механизм перевода `createTranslator(словарь)`. Код вне компонентов берёт текущий язык через `getLanguage()` (например, для заголовка `Accept-Language`), ключ хранилища и язык по умолчанию в приложениях не повторяются; серверный код переводит функцией `translate(словарь, язык, ключ)` на язык запроса, разобранный `resolveLanguage(Accept-Language)`. Приложения (DevCloud, WebApp, терминал) свой список языков, хранилище и функцию перевода не держат: берут их из библиотеки и строят свой `$T` из своего словаря — `export const T = createTranslator(translations)`. Одно `setLanguage` переключает и компоненты библиотеки, и приложение. Многоязычные тексты GUI распознаются по виду ключей (коды языков), поэтому данные с языком, убранным из списка, не ломаются.
 
 **Языки (ru/en/zh) — два слоя:**
 

package/dist/locales/i18n.d.ts

@@ -1,6 +1,7 @@
 import { type Readable } from "svelte/store";
 import { type LanguageCode, type Translations } from "./languages";
 export declare const Language: import("svelte/store").Writable<string>;
+export declare const getLanguage: () => LanguageCode;
 export declare function restoreLanguage(): void;
 export declare function setLanguage(newLang: string): void;
 export declare const LOCALES: {
@@ -11,5 +12,6 @@ export declare const LOCALES: {
 }[];
 export type TranslateParams = Record<string, string | number>;
 export type Translator = (key: string, params?: TranslateParams) => string;
+export declare const translate: (dictionary: Translations, locale: string, 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,6 +1,6 @@
-import { derived, writable } from "svelte/store";
+import { derived, get, writable } from "svelte/store";
 import translations from "./translations";
-import { DEFAULT_LANGUAGE, LANGUAGES, isLanguageCode } from "./languages";
+import { DEFAULT_LANGUAGE, LANGUAGES, isLanguageCode, resolveLanguage } from "./languages";
 /* Язык и механизм перевода — общие для библиотеки и приложений: приложение берёт отсюда Language/setLanguage/LOCALES и строит свой $T
    из своего словаря через createTranslator (см. README «Языки»); переключение языка одним setLanguage меняет и компоненты, и приложение */
 /*
@@ -8,6 +8,8 @@ import { DEFAULT_LANGUAGE, LANGUAGES, isLanguageCode } from "./languages";
   гидратации); сохранённый выбор применяет restoreLanguage(): в SSR-приложениях — в onMount корневого layout, в SPA — при старте
 */
 export const Language = writable(DEFAULT_LANGUAGE);
+/* Текущий язык — для заголовков запросов (Accept-Language) и прочего кода вне компонентов */
+export const getLanguage = () => resolveLanguage(get(Language));
 /* Сохранённый язык → язык браузера; неизвестный код не применяется */
 export function restoreLanguage() {
     if (typeof window === "undefined")
@@ -44,8 +46,8 @@ export const LOCALES = LANGUAGES.map((language) => ({
     value: language.value,
     flag: language.flag,
 }));
-/* Перевод по словарю: текущий язык → язык по умолчанию → сам ключ */
-const translate = (dictionary, locale, key, params) => {
+/* Перевод по словарю на заданный язык: язык → язык по умолчанию → сам ключ; без хранилища — для серверного кода (язык запроса) */
+export const translate = (dictionary, locale, key, params) => {
     const row = dictionary[key];
     const text = (row && (row[locale] || row[DEFAULT_LANGUAGE])) || key;
     return params ? text.replace(/\{(\w+)\}/g, (match, name) => (name in params ? String(params[name]) : match)) : text;

package/dist/locales/languages.d.ts

@@ -17,6 +17,7 @@ export declare const LANGUAGE_CODES: LanguageCode[];
 export type Translation = Record<typeof DEFAULT_LANGUAGE, string> & Partial<Record<LanguageCode, string>>;
 export type Translations = Record<string, Translation>;
 export declare const isLanguageCode: (value: unknown) => value is LanguageCode;
+export declare const resolveLanguage: (value: string | null | undefined) => LanguageCode;
 export declare const findMissingTranslations: (dictionary: Translations) => {
     key: string;
     languages: LanguageCode[];

package/dist/locales/languages.js

@@ -26,6 +26,11 @@ export const DEFAULT_LANGUAGE = "ru";
 /* Коды в порядке LANGUAGES — порядок показа в переключателях и колонках переводов */
 export const LANGUAGE_CODES = LANGUAGES.map((language) => language.value);
 export const isLanguageCode = (value) => LANGUAGE_CODES.includes(value);
+/* Код языка из произвольного значения (код, заголовок Accept-Language «en-US,en;q=0.9», язык браузера); неизвестный — язык по умолчанию */
+export const resolveLanguage = (value) => {
+    const code = value?.split(/[,;]/)[0]?.trim().split("-")[0]?.toLowerCase();
+    return isLanguageCode(code) ? code : DEFAULT_LANGUAGE;
+};
 /* Ключи словаря без перевода на какой-либо язык — для проверки полноты словаря при добавлении языка */
 export const findMissingTranslations = (dictionary) => Object.entries(dictionary)
     .map(([key, row]) => ({ key, languages: LANGUAGE_CODES.filter((code) => !row[code]) }))

package/package.json

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