@intlayer/docs 8.0.4 → 8.0.5

package/docs/ru/intlayer_with_analog.md

@@ -0,0 +1,371 @@
+---
+createdAt: 2025-04-18
+updatedAt: 2025-12-30
+title: Analog i18n - Как перевести ваше приложение Analog – руководство 2026
+description: Узнайте, как сделать ваше приложение Analog многоязычным. Следуйте документации для интернационализации (i18n) и перевода.
+keywords:
+  - Интернационализация
+  - Документация
+  - Intlayer
+  - Analog
+  - Angular
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - analog
+applicationTemplate: https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template
+history:
+  - version: 8.0.4
+    date: 2026-01-26
+    changes: Инициализация истории
+---
+
+# Переведите ваше приложение Analog (Angular) с помощью Intlayer | Интернационализация (i18n)
+
+## Содержание
+
+<TOC/>
+
+## Что такое Intlayer?
+
+**Intlayer** — это инновационная библиотека интернационализации (i18n) с открытым исходным кодом, разработанная для упрощения поддержки многоязычности в современных веб-приложениях.
+
+С помощью Intlayer вы можете:
+
+- **Легко управлять переводами**, используя декларативные словари на уровне компонентов.
+- **Динамически локализовать метаданные**, маршруты и контент.
+- **Обеспечить поддержку TypeScript** с помощью автоматически генерируемых типов, улучшая автодополнение и обнаружение ошибок.
+- **Пользоваться расширенными функциями**, такими как динамическое определение и переключение языка (locale).
+
+---
+
+## Пошаговое руководство по настройке Intlayer в приложении Analog
+
+<Tabs defaultTab="code">
+  <Tab label="Код" value="code">
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer/tree/main/examples/vite-analog-app?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"
+/>
+
+  </Tab>
+</Tabs>
+
+См. [Шаблон приложения](https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template) на GitHub.
+
+### Шаг 1: Установка зависимостей
+
+Установите необходимые пакеты с помощью npm:
+
+```bash packageManager="npm"
+npm install intlayer angular-intlayer vite-intlayer
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer angular-intlayer vite-intlayer
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer angular-intlayer vite-intlayer
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer angular-intlayer vite-intlayer
+bunx intlayer init
+```
+
+- **intlayer**
+
+  Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, [декларации контента](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/cli/index.md).
+
+- **angular-intlayer**
+  Пакет для интеграции Intlayer с приложением Angular. Предоставляет провайдеры контекста и хуки для интернационализации Angular.
+
+- **vite-intlayer**
+  Пакет для интеграции Intlayer с Vite. Предоставляет плагин для обработки файлов декларации контента и настраивает алиасы для оптимальной производительности.
+
+### Шаг 2: Конфигурация вашего проекта
+
+Создайте конфигурационный файл для настройки языков вашего приложения:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      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,
+  },
+};
+
+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, имена куки, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в [документации по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).
+
+### Шаг 3: Интеграция Intlayer в конфигурацию Vite
+
+Для интеграции Intlayer с Analog вам необходимо использовать плагин `vite-intlayer`.
+
+Измените файл `vite.config.ts`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+import analog from "@analogjs/platform";
+
+// https://vitejs.dev/config/
+export default defineConfig(() => ({
+  plugins: [
+    analog(),
+    intlayer(), // Добавьте плагин Intlayer
+  ],
+}));
+```
+
+> Плагин `intlayer()` настраивает Vite для работы с Intlayer. Он обрабатывает файлы декларации контента и устанавливает алиасы для оптимальной производительности.
+
+### Шаг 4: Декларация вашего контента
+
+Создавайте и управляйте декларациями контента для хранения переводов:
+
+```tsx fileName="src/app/app.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+      ru: "Привет",
+    }),
+    congratulations: t({
+      en: "Congratulations! Your app is running. 🎉",
+      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
+      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
+      ru: "Поздравляем! Ваше приложение запущено. 🎉",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+> Декларации контента могут быть определены в любом месте вашего приложения, если они включены в каталог `contentDir` (по умолчанию `./src`) и соответствуют расширению файла декларации контента (по умолчанию `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+
+> Для получения более подробной информации см. [документацию по декларации контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/content_file.md).
+
+### Шаг 5: Использование Intlayer в вашем коде
+
+Чтобы использовать функции интернационализации Intlayer во всем приложении Analog, вам необходимо добавить Intlayer в конфигурацию приложения.
+
+```typescript fileName="src/app/app.config.ts"
+import { ApplicationConfig } from "@angular/core";
+import { provideIntlayer } from "angular-intlayer";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideIntlayer(), // Добавьте провайдер Intlayer здесь
+  ],
+};
+```
+
+Затем вы можете использовать функцию `useIntlayer` в любом компоненте.
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  template: `
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+Контент Intlayer возвращается как `Signal`, поэтому вы получаете доступ к значениям, вызывая сигнал: `content().title`.
+
+### (Опционально) Шаг 6: Изменение языка вашего контента
+
+Для изменения языка вашего контента вы можете использовать функцию `setLocale`, предоставляемую функцией `useLocale`. Это позволяет вам установить язык приложения и соответствующим образом обновить контент.
+
+Создайте компонент для переключения языков:
+
+```typescript fileName="src/app/locale-switcher.component.ts"
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { useLocale } from "angular-intlayer";
+
+@Component({
+  selector: "app-locale-switcher",
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div class="locale-switcher">
+      <select
+        [value]="locale()"
+        (change)="setLocale($any($event.target).value)"
+      >
+        @for (loc of availableLocales; track loc) {
+          <option [value]="loc">{{ loc }}</option>
+        }
+      </select>
+    </div>
+  `,
+  styles: [
+    `
+      .locale-switcher {
+        margin: 1rem;
+        padding: 0.5rem;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        width: fit-content;
+      }
+    `,
+  ],
+})
+export class LocaleSwitcherComponent {
+  localeCtx = useLocale();
+
+  locale = this.localeCtx.locale;
+  availableLocales = this.localeCtx.availableLocales;
+  setLocale = this.localeCtx.setLocale;
+}
+```
+
+Затем используйте этот компонент на своих страницах:
+
+```typescript fileName="src/app/pages/index.page.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+import { LocaleSwitcherComponent } from "../locale-switcher.component";
+
+@Component({
+  selector: "app-home",
+  standalone: true,
+  imports: [LocaleSwitcherComponent],
+  template: `
+    <app-locale-switcher></app-locale-switcher>
+    <div class="content">
+      <h1>{{ content().title }}</h1>
+      <p>{{ content().congratulations }}</p>
+    </div>
+  `,
+})
+export default class HomeComponent {
+  content = useIntlayer("app");
+}
+```
+
+### Настройка TypeScript
+
+Intlayer использует расширение модулей (module augmentation) для получения преимуществ TypeScript и усиления вашей кодовой базы.
+
+![Автодополнение](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Ошибка перевода](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Убедитесь, что ваша конфигурация TypeScript включает автоматически генерируемые типы.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Ваши существующие конфигурации TypeScript
+  "include": [
+    // ... Ваши существующие конфигурации TypeScript
+    ".intlayer/**/*.ts", // Включить автоматически генерируемые типы
+  ],
+}
+```
+
+### Конфигурация Git
+
+Рекомендуется игнорировать файлы, генерируемые Intlayer. Это позволит вам избежать их коммита в ваш Git-репозиторий.
+
+Для этого вы можете добавить следующие инструкции в ваш файл `.gitignore`:
+
+```plaintext
+# Игнорировать файлы, генерируемые Intlayer
+.intlayer
+```
+
+### Расширение VS Code
+
+Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное **расширение Intlayer для VS Code**.
+
+[Установить из VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-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).

package/docs/ru/intlayer_with_angular.md

@@ -166,30 +166,28 @@ module.exports = config;
 
 Сначала измените ваш `angular.json`, чтобы использовать пользовательский билдер Webpack. Обновите конфигурации `build` и `serve`:
 
-```json fileName="angular.json"
+```json5 fileName="angular.json"
 {
   "projects": {
     "your-app-name": {
       "architect": {
         "build": {
-          "builder": "@angular-builders/custom-webpack:browser",
+          "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",
           "options": {
             "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
+              "path": "./webpack.config.ts",
+              "mergeStrategies": { "module.rules": "prepend" },
+            },
+            "main": "src/main.ts", // replace "browser": "src/main.ts",
+            // ...
+          },
         },
         "serve": {
           "builder": "@angular-builders/custom-webpack:dev-server",
-          "options": {
-            "customWebpackConfig": {
-              "path": "./webpack.config.ts"
-            }
-          }
-        }
-      }
-    }
-  }
+        },
+      },
+    },
+  },
 }
 ```
 

package/docs/ru/packages/solid-intlayer/useIntlayer.md

@@ -33,7 +33,7 @@ history:
 import { useIntlayer } from "solid-intlayer";
 
 const MyComponent = () => {
-  const content = useIntlayer("my_dictionary_key");
+  const content = useIntlayer("my-dictionary-key");
 
   return (
     <div>

package/docs/tr/cli/doc-translate.md

@@ -86,6 +86,7 @@ npx intlayer doc translate
 - **`--temperature [temperature]`**: Yapay zeka modeli için sıcaklık ayarı.
 - **`--api-key [apiKey]`**: Yapay zeka servisi için kendi API anahtarınızı sağlayın.
 - **`--application-context [applicationContext]`**: Yapay zeka çevirisi için ek bağlam sağlayın.
+- **`--data-serialization [dataSerialization]`**: Intlayer'ın AI özellikleri için kullanılacak veri serileştirme formatı. Seçenekler: `json` (standart, güvenilir), `toon` (daha az jeton, daha az tutarlı).
 - **`--custom-prompt [prompt]`**: Çeviri için kullanılan temel promptu özelleştirin. (Not: Çoğu kullanım durumu için, çeviri davranışı üzerinde daha iyi kontrol sağladığı için `--custom-instructions` seçeneği önerilir.)
 
   > Örnek: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`

package/docs/tr/cli/fill.md

@@ -126,6 +126,7 @@ Affected dictionary keys for processing: app, comp-test, hello-world, lang-switc
 - **`--api-key [apiKey]`**: AI servisi için kendi API anahtarınızı sağlayın.
 - **`--custom-prompt [prompt]`**: Çeviri talimatlarınız için özel bir prompt sağlayın.
 - **`--application-context [applicationContext]`**: AI çevirisi için ek bağlam sağlayın.
+- **`--data-serialization [dataSerialization]`**: Intlayer'ın AI özellikleri için kullanılacak veri serileştirme formatı. Seçenekler: `json` (standart, güvenilir), `toon` (daha az jeton, daha az tutarlı).
 
   > Örnek: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "Uygulamam bir kedi mağazasıdır"`
 

package/docs/tr/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: AI yapılandırmasına `dataSerialization` eklendi
   - version: 8.0.0
     date: 2026-01-22
     changes: Move `importMode` build configuration to `dictionary` configuration.
@@ -888,6 +891,13 @@ Intlayer, artırılmış esneklik ve seçenek için birden fazla AI sağlayıcı
   - _Örnek_: `'https://api.openai.com/v1'`
   - _Not_: Yerel veya özel bir AI API uç noktasını işaret etmek için kullanılabilir.
 
+- **dataSerialization**:
+  - _Tür_: `'json' | 'toon'`
+  - _Varsayılan_: `'json'`
+  - _Açıklama_: Intlayer'ın AI özellikleri için kullanılacak veri serileştirme formatı.
+  - _Örnek_: `'toon'`
+  - _Not_: `json`: Standart, güvenilir; daha fazla jeton kullanır. `toon`: Daha az jeton, JSON'dan daha az tutarlı.
+
 ### Derleme Yapılandırması
 
 Intlayer'ın uygulamanızın uluslararasılaştırmasını nasıl optimize edip derleyeceğini kontrol eden ayarlar.