@intlayer/docs 7.1.9 → 7.2.2

package/docs/ru/intlayer_with_vite+svelte.md

@@ -1,7 +1,7 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2025-06-29
-title: Как перевести ваше Vite and Svelte – руководство i18n 2025
+updatedAt: 2025-11-19
+title: Как перевести ваше приложение на Vite и Svelte – руководство по i18n 2025
 description: Узнайте, как сделать ваш сайт на Vite и Svelte многоязычным. Следуйте документации для интернационализации (i18n) и перевода.
 keywords:
   - Интернационализация
@@ -14,34 +14,47 @@ slugs:
   - doc
   - environment
   - vite-and-svelte
-# applicationTemplate: https://github.com/aymericzip/intlayer-vite-solid-template
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-svelte-template
 history:
+  - version: 5.5.11
+    date: 2025-11-19
+    changes: Обновление документации
   - version: 5.5.10
     date: 2025-06-29
     changes: Инициализация истории
 ---
 
-# Переведите ваш Vite and Svelte с Intlayer | Интернационализация (i18n)
+# Перевод вашего сайта на Vite и Svelte с использованием Intlayer | Интернационализация (i18n)
 
-> Этот пакет находится в разработке. Подробнее смотрите в [issue](https://github.com/aymericzip/intlayer/issues/114). Покажите свой интерес к Intlayer для Svelte, поставив лайк этому issue.
+## Содержание
 
-<!-- Смотрите [шаблон приложения](https://github.com/aymericzip/intlayer-solid-template) на GitHub. -->
+<TOC/>
 
 ## Что такое Intlayer?
 
-**Intlayer** - это инновационная, открытая библиотека интернационализации (i18n), разработанная для упрощения поддержки многоязычности в современных веб-приложениях.
+**Intlayer** — это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.
 
-С помощью Intlayer вы можете:
+С Intlayer вы можете:
 
-- **Легко управлять переводами** с использованием декларативных словарей на уровне компонентов.
+- **Легко управлять переводами** с помощью декларативных словарей на уровне компонентов.
 - **Динамически локализовать метаданные**, маршруты и контент.
-- **Обеспечить поддержку TypeScript** с помощью автогенерируемых типов, улучшая автодополнение и обнаружение ошибок.
-- **Воспользуйтесь расширенными возможностями**, такими как динамическое определение и переключение локали.
+- **Обеспечить поддержку TypeScript** с автогенерируемыми типами, улучшая автодополнение и обнаружение ошибок.
+- **Воспользоваться расширенными возможностями**, такими как динамическое определение и переключение локали.
 
 ---
 
 ## Пошаговое руководство по настройке Intlayer в приложении на Vite и Svelte
 
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-vite-react-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Демонстрация CodeSandbox - Как интернационализировать ваше приложение с помощью Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+Смотрите [Шаблон приложения](https://github.com/aymericzip/intlayer-vite-svelte-template) на GitHub.
+
 ### Шаг 1: Установка зависимостей
 
 Установите необходимые пакеты с помощью npm:
@@ -61,23 +74,26 @@ yarn add intlayer svelte-intlayer
 yarn add vite-intlayer --save-dev
 ```
 
-- **intlayer**
+```bash packageManager="bun"
+bun add intlayer svelte-intlayer
+bun add vite-intlayer --save-dev
+```
 
 - **intlayer**
 
-  Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, [объявления контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/get_started.md), транспиляции и [CLI-команд](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md).
+  Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, [объявления контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/content_file.md), транспиляции и [CLI-команд](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md).
 
 - **svelte-intlayer**
   Пакет, который интегрирует Intlayer с приложением на Svelte. Он предоставляет провайдеры контекста и хуки для интернационализации в Svelte.
 
 - **vite-intlayer**
-  Включает плагин Vite для интеграции Intlayer с [сборщиком Vite](https://vite.dev/guide/why.html#why-bundle-for-production), а также middleware для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.
+  Включает плагин Vite для интеграции Intlayer с [сборщиком Vite](https://vite.dev/guide/why.html#why-bundle-for-production), а также middleware для определения предпочтительной локали пользователя, управления cookie и обработки перенаправления URL.
 
 ### Шаг 2: Конфигурация вашего проекта
 
 Создайте файл конфигурации для настройки языков вашего приложения:
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
@@ -88,25 +104,7 @@ const config: IntlayerConfig = {
       Locales.SPANISH,
       // Ваши другие локали
     ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
 
-export default config;
-```
-
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Ваши другие локали
-    ],
     defaultLocale: Locales.ENGLISH,
   },
 };
@@ -114,44 +112,13 @@ const config = {
 export default config;
 ```
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
-
-/** @type {import('intlayer').IntlayerConfig} */
-// Конфигурация интернационализации
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Ваши другие локали
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-module.exports = config;
-```
-
-> Через этот конфигурационный файл вы можете настроить локализованные URL, перенаправление в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к [документации по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).
+> Через этот файл конфигурации вы можете настроить локализованные URL, перенаправление в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к [документации по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).
 
 ### Шаг 3: Интеграция Intlayer в вашу конфигурацию Vite
 
 Добавьте плагин intlayer в вашу конфигурацию.
 
-```typescript fileName="vite.config.ts" codeFormat="typescript"
-import { defineConfig } from "vite";
-import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [svelte(), intlayer()],
-});
-```
-
-```javascript fileName="vite.config.mjs" codeFormat="esm"
+```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
 import { intlayer } from "vite-intlayer";
@@ -162,20 +129,9 @@ export default defineConfig({
 });
 ```
 
-```javascript fileName="vite.config.cjs" codeFormat="commonjs"
-const { defineConfig } = require("vite");
-const react = require("@vitejs/plugin-react-swc");
-const { intlayer } = require("vite-intlayer");
-
-// https://vitejs.dev/config/
-module.exports = defineConfig({
-  plugins: [react(), intlayer()],
-});
-```
+> Плагин Vite `intlayer()` используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, предоставляет алиасы для оптимизации производительности.
 
-> Плагин Vite `intlayer()` используется для интеграции Intlayer с Vite. Он обеспечивает создание файлов деклараций контента и отслеживает их в режиме разработки. Он определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, он предоставляет алиасы для оптимизации производительности.
-
-### Шаг 4: Объявите Ваш Контент
+### Шаг 4: Объявите ваш контент
 
 Создайте и управляйте декларациями контента для хранения переводов:
 
@@ -200,6 +156,7 @@ export default appContent;
 import { t } from "intlayer";
 
 /** @type {import('intlayer').Dictionary} */
+// Объявление словаря контента приложения
 const appContent = {
   key: "app",
   content: {
@@ -218,7 +175,7 @@ export default appContent;
 const { t } = require("intlayer");
 
 /** @type {import('intlayer').Dictionary} */
-// Объявление словаря контента
+// Объявление словаря контента приложения
 const appContent = {
   key: "app",
   content: {
@@ -250,33 +207,254 @@ module.exports = appContent;
 }
 ```
 
-> Ваши декларации контента могут быть определены в любом месте вашего приложения, как только они будут включены в директорию `contentDir` (по умолчанию, `./src`). И соответствовать расширению файла декларации контента (по умолчанию, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+> Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они будут включены в директорию `contentDir` (по умолчанию, `./src`). И соответствовать расширению файла объявления контента (по умолчанию, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
 
-> Для получения дополнительной информации обратитесь к [документации по объявлению контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/get_started.md).
+> Для получения дополнительной информации обратитесь к [документации по объявлению контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/content_file.md).
 
 ### Шаг 5: Использование Intlayer в вашем коде
 
-[заполнить]
+```svelte fileName="src/App.svelte"
+<script>
+  import { useIntlayer } from "svelte-intlayer";
+
+  const content = useIntlayer("app");
+</script>
+
+<div>
+
+
+<!-- Отобразить контент как простой контент -->
+<h1>{$content.title}</h1>
+<!-- Отобразить контент с возможностью редактирования через редактор -->
+<h1><svelte:component this={$content.title} /></h1>
+<!-- Отобразить контент как строку -->
+<div aria-label={$content.title.value}></div>
+```
 
 ### (Необязательно) Шаг 6: Изменение языка вашего контента
 
-[заполнить]
+```svelte fileName="src/App.svelte"
+<script lang="ts">
+import  { getLocaleName } from 'intlayer';
+import { useLocale } from 'svelte-intlayer';
+
+// Получить информацию о локали и функцию setLocale
+const { locale, availableLocales, setLocale } = useLocale();
+
+// Обработка изменения локали
+const changeLocale = (event: Event) => {
+  const target = event.target as HTMLSelectElement;
+  const newLocale = target.value;
+  setLocale(newLocale);
+};
+</script>
+
+<div>
+  <select value={$locale} on:change={changeLocale}>
+    {#each availableLocales ?? [] as loc}
+      <option value={loc}>
+        {getLocaleName(loc)}
+      </option>
+    {/each}
+  </select>
+</div>
+```
+
+### (Необязательно) Шаг 7: Отображение Markdown
+
+Intlayer поддерживает отображение контента в формате Markdown непосредственно в вашем приложении на Svelte. По умолчанию Markdown обрабатывается как простой текст. Чтобы преобразовать Markdown в насыщенный HTML, вы можете интегрировать `@humanspeak/svelte-markdown` или другой парсер Markdown.
+
+> Чтобы узнать, как объявлять контент в формате markdown с использованием пакета `intlayer`, смотрите [документацию по markdown](https://github.com/aymericzip/intlayer/tree/main/docs/docs/ru/dictionary/markdown.md).
+
+```svelte fileName="src/App.svelte"
+<script>
+  import { setIntlayerMarkdown } from "svelte-intlayer";
+
+  setIntlayerMarkdown((markdown) =>
+   // рендеринг содержимого markdown как строки
+   return markdown;
+  );
+</script>
+
+<h1>{$content.markdownContent}</h1>
+```
+
+> Вы также можете получить доступ к данным front-matter вашего markdown через свойство `content.markdownContent.metadata.xxx`.
 
-### (Необязательно) Шаг 7: Добавление локализованной маршрутизации в ваше приложение
+### (Необязательно) Шаг 8: Настройка редактора / CMS intlayer
 
-[заполнить]
+Для настройки редактора intlayer необходимо следовать [документации редактора intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md).
+
+Для настройки CMS intlayer необходимо следовать [документации CMS intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md).
+
+Параллельно, в вашем приложении на Svelte, вы должны добавить следующую строку в layout или в корень вашего приложения:
+
+```svelte fileName="src/layout.svelte"
+import { useIntlayerEditor } from "svelte-intlayer";
+
+useIntlayerEditor();
+```
+
+### (Необязательно) Шаг 7: Добавьте локализованную маршрутизацию в ваше приложение
+
+Для обработки локализованной маршрутизации в вашем приложении на Svelte вы можете использовать `svelte-spa-router` вместе с `localeFlatMap` из Intlayer для генерации маршрутов для каждой локали.
+
+Сначала установите `svelte-spa-router`:
+
+```bash packageManager="npm"
+npm install svelte-spa-router
+```
+
+```bash packageManager="pnpm"
+pnpm add svelte-spa-router
+```
+
+```bash packageManager="yarn"
+yarn add svelte-spa-router
+```
+
+```bash packageManager="bun"
+bun add svelte-spa-router
+```
+
+Затем создайте файл `Router.svelte` для определения ваших маршрутов:
+
+```svelte fileName="src/Router.svelte"
+<script lang="ts">
+import { localeFlatMap } from "intlayer";
+import Router from "svelte-spa-router";
+import { wrap } from "svelte-spa-router/wrap";
+import App from "./App.svelte";
+
+const routes = Object.fromEntries(
+    localeFlatMap(({locale, urlPrefix}) => [
+    [
+        urlPrefix || '/',
+        wrap({
+            component: App as any,
+            props: {
+                locale,
+            },
+        }),
+    ],
+    ])
+);
+</script>
+
+<Router {routes} />
+```
+
+Обновите ваш `main.ts`, чтобы монтировать компонент `Router` вместо `App`:
+
+```typescript fileName="src/main.ts"
+import { mount } from "svelte";
+import Router from "./Router.svelte";
+
+const app = mount(Router, {
+  target: document.getElementById("app")!,
+});
+
+export default app;
+```
+
+Наконец, обновите ваш `App.svelte`, чтобы принимать проп `locale` и использовать его с `useIntlayer`:
+
+```svelte fileName="src/App.svelte"
+<script lang="ts">
+import type { Locale } from 'intlayer';
+import { useIntlayer } from 'svelte-intlayer';
+import Counter from './lib/Counter.svelte';
+import LocaleSwitcher from './lib/LocaleSwitcher.svelte';
+
+export let locale: Locale;
+
+// Используем хук useIntlayer для получения контента на основе текущей локали
+$: content = useIntlayer('app', locale);
+</script>
+
+<main>
+  <div class="locale-switcher-container">
+    <LocaleSwitcher currentLocale={locale} />
+  </div>
+
+  <!-- ... остальная часть вашего приложения ... -->
+</main>
+```
+
+#### Настройка маршрутизации на стороне сервера (необязательно)
+
+Параллельно вы также можете использовать `intlayerProxy` для добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующее cookie с локалью. Если локаль не указана, плагин определит наиболее подходящую локаль на основе языковых предпочтений браузера пользователя. Если локаль не будет обнаружена, произойдет перенаправление на локаль по умолчанию.
+
+> Обратите внимание, что для использования `intlayerProxy` в продакшене необходимо перевести пакет `vite-intlayer` из `devDependencies` в `dependencies`.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { svelte } = require("@sveltejs/vite-plugin-svelte");
+const { intlayer, intlayerProxy } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
 
 ### (Необязательно) Шаг 8: Изменение URL при смене локали
 
-[заполнить]
+Чтобы позволить пользователям переключать языки и обновлять URL соответствующим образом, вы можете создать компонент `LocaleSwitcher`. Этот компонент будет использовать `getLocalizedUrl` из `intlayer` и `push` из `svelte-spa-router`.
 
-### (Необязательно) Шаг 9: Переключение атрибутов языка и направления HTML
+```svelte fileName="src/lib/LocaleSwitcher.svelte"
+<script lang="ts">
+import { getLocaleName, getLocalizedUrl } from "intlayer";
+import { useLocale } from "svelte-intlayer";
+import { push } from "svelte-spa-router";
 
-[заполнить]
+export let currentLocale: string | undefined = undefined;
 
-### (Необязательно) Шаг 10: Создание локализованного компонента ссылки
+// Получение информации о локали
+const { locale, availableLocales } = useLocale();
 
-[заполнить]
+// Обработка изменения локали
+const changeLocale = (event: Event) => {
+  const target = event.target as HTMLSelectElement;
+  const newLocale = target.value;
+  const currentUrl = window.location.pathname;
+  const url = getLocalizedUrl( currentUrl, newLocale);
+  push(url);
+};
+</script>
+
+<div class="locale-switcher">
+  <select value={currentLocale ?? $locale} onchange={changeLocale}>
+    {#each availableLocales ?? [] as loc}
+      <option value={loc}>
+        {getLocaleName(loc)}
+      </option>
+    {/each}
+  </select>
+</div>
+```
 
 ### Конфигурация Git
 
@@ -291,23 +469,21 @@ module.exports = appContent;
 
 ### Расширение VS Code
 
-Для улучшения вашего опыта разработки с Intlayer вы можете установить официальное **расширение Intlayer для VS Code**.
+Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное расширение **Intlayer для VS Code**.
 
-[Установить из магазина расширений VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+[Установить из VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
 Это расширение предоставляет:
 
-- **Автозаполнение** ключей перевода.
+- **Автозаполнение** ключей переводов.
 - **Обнаружение ошибок в реальном времени** для отсутствующих переводов.
 - **Встроенный просмотр** переведенного контента.
 - **Быстрые действия** для удобного создания и обновления переводов.
 
-Для получения дополнительной информации о том, как использовать расширение, обратитесь к [документации по расширению Intlayer для VS Code](https://intlayer.org/doc/vs-code-extension).
+Для получения дополнительной информации о том, как использовать расширение, обратитесь к [документации расширения Intlayer для VS Code](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
-### Продвинутые возможности
+### Продвинуться дальше
 
-Для расширения возможностей вы можете реализовать [визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md) или вынести ваш контент во внешний [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md).
-
----
+Чтобы продвинуться дальше, вы можете реализовать [визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md) или вынести ваш контент, используя [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md).