@intlayer/docs 8.0.4 → 8.0.5

package/docs/it/intlayer_with_analog.md

@@ -0,0 +1,371 @@
+---
+createdAt: 2025-04-18
+updatedAt: 2025-12-30
+title: Analog i18n - Come tradurre la tua app Analog – guida 2026
+description: Scopri come rendere la tua app Analog multilingue. Segui la documentazione per internazionalizzarla (i18n) e tradurla.
+keywords:
+  - Internationalization
+  - Documentation
+  - 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: Init history
+---
+
+# Traduci la tua app Analog (Angular) usando Intlayer | Internazionalizzazione (i18n)
+
+## Sommario
+
+<TOC/>
+
+## Cos'è Intlayer?
+
+**Intlayer** è una libreria di internazionalizzazione (i18n) innovativa e open source progettata per semplificare il supporto multilingue nelle moderne applicazioni web.
+
+Con Intlayer, puoi:
+
+- **Gestire facilmente le traduzioni** utilizzando dizionari dichiarativi a livello di componente.
+- **Localizzare dinamicamente metadati, percorsi e contenuti**.
+- **Garantire il supporto TypeScript** con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
+- **Beneficiare di funzionalità avanzate**, come il rilevamento e la commutazione dinamica della lingua.
+
+---
+
+## Guida Passo-Passo per Configurare Intlayer in un'Applicazione Analog
+
+<Tabs defaultTab="code">
+  <Tab label="Code" 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="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+Vedi il [Template dell'Applicazione](https://github.com/aymericzip/intlayer/tree/main/examples/analog-app-template) su GitHub.
+
+### Passaggio 1: Installa le Dipendenze
+
+Installa i pacchetti necessari utilizzando 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**
+
+  Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, la traduzione, la [dichiarazione dei contenuti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md), la traspilazione e i [comandi CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/index.md).
+
+- **angular-intlayer**
+  Il pacchetto che integra Intlayer con l'applicazione Angular. Fornisce provider di contesto e hook per l'internazionalizzazione di Angular.
+
+- **vite-intlayer**
+  Il pacchetto che integra Intlayer con Vite. Fornisce un plugin per gestire i file di dichiarazione dei contenuti e imposta gli alias per prestazioni ottimali.
+
+### Passaggio 2: Configurazione del tuo Progetto
+
+Crea un file di configurazione per configurare le lingue della tua applicazione:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Le tue altre lingue
+    ],
+    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,
+      // Le tue altre lingue
+    ],
+    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,
+      // Le tue altre lingue
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamento middleware, nomi dei cookie, la posizione e l'estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, consulta la [documentazione della configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
+
+### Passaggio 3: Integra Intlayer nella tua Configurazione Vite
+
+Per integrare Intlayer con Analog, devi utilizzare il plugin `vite-intlayer`.
+
+Modifica il tuo file `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(), // Aggiungi il plugin Intlayer
+  ],
+}));
+```
+
+> Il plugin `intlayer()` configura Vite con Intlayer. Gestisce i file di dichiarazione dei contenuti e imposta gli alias per prestazioni ottimali.
+
+### Passaggio 4: Dichiarazione dei Contenuti
+
+Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:
+
+```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",
+      it: "Ciao",
+    }),
+    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. 🎉",
+      it: "Congratulazioni! La tua app è in esecuzione. 🎉",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+> Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione purché siano incluse nella directory `contentDir` (per impostazione predefinita, `./src`). E corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+
+> Per maggiori dettagli, fai riferimento alla [documentazione sulla dichiarazione dei contenuti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md).
+
+### Passaggio 5: Utilizza Intlayer nel tuo Codice
+
+Per utilizzare le funzionalità di internazionalizzazione di Intlayer in tutta la tua applicazione Analog, devi fornire Intlayer nella configurazione dell'applicazione.
+
+```typescript fileName="src/app/app.config.ts"
+import { ApplicationConfig } from "@angular/core";
+import { provideIntlayer } from "angular-intlayer";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideIntlayer(), // Aggiungi il provider Intlayer qui
+  ],
+};
+```
+
+Quindi, puoi utilizzare la funzione `useIntlayer` all'interno di qualsiasi componente.
+
+```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");
+}
+```
+
+Il contenuto di Intlayer viene restituito come un `Signal`, quindi accedi ai valori chiamando il segnale: `content().title`.
+
+### (Opzionale) Passaggio 6: Cambia la lingua del tuo contenuto
+
+Per cambiare la lingua del tuo contenuto, puoi utilizzare la funzione `setLocale` fornita dalla funzione `useLocale`. Ciò ti consente di impostare la localizzazione dell'applicazione e aggiornare il contenuto di conseguenza.
+
+Crea un componente per passare da una lingua all'altra:
+
+```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;
+}
+```
+
+Quindi, usa questo componente nelle tue pagine:
+
+```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");
+}
+```
+
+### Configura TypeScript
+
+Intlayer utilizza l'aumento dei moduli (module augmentation) per trarre vantaggio da TypeScript e rendere più solida la tua base di codice.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Assicurati che la tua configurazione TypeScript includa i tipi generati automaticamente.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Le tue configurazioni TypeScript esistenti
+  "include": [
+    // ... Le tue configurazioni TypeScript esistenti
+    ".intlayer/**/*.ts", // Includi i tipi generati automaticamente
+  ],
+}
+```
+
+### Configurazione Git
+
+Si consiglia di ignorare i file generati da Intlayer. Ciò consente di evitare di caricarli nel repository Git.
+
+Per fare ciò, puoi aggiungere le seguenti istruzioni al tuo file `.gitignore`:
+
+```plaintext
+# Ignora i file generati da Intlayer
+.intlayer
+```
+
+### Estensione VS Code
+
+Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'**Estensione Intlayer per VS Code** ufficiale.
+
+[Installa dal Marketplace di VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+Questa estensione fornisce:
+
+- **Autocompletamento** per le chiavi di traduzione.
+- **Rilevamento degli errori in tempo reale** per le traduzioni mancanti.
+- **Anteprime in linea** del contenuto tradotto.
+- **Azioni rapide** per creare e aggiornare facilmente le traduzioni.
+
+Per maggiori dettagli su come utilizzare l'estensione, consulta la [documentazione dell'estensione Intlayer per VS Code](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Approfondimenti
+
+Per andare oltre, puoi implementare l'[editor visuale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md) o esternalizzare i tuoi contenuti utilizzando il [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md).

package/docs/it/intlayer_with_angular.md

@@ -166,30 +166,28 @@ Per integrare Intlayer con Angular CLI, è necessario utilizzare un builder pers
 
 Per prima cosa, modifica il tuo `angular.json` per utilizzare il builder Webpack personalizzato. Aggiorna le configurazioni `build` e `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/it/packages/solid-intlayer/useIntlayer.md

@@ -33,7 +33,7 @@ L'hook `useIntlayer` ti permette di recuperare contenuti localizzati da un dizio
 import { useIntlayer } from "solid-intlayer";
 
 const MyComponent = () => {
-  const content = useIntlayer("my_dictionary_key");
+  const content = useIntlayer("my-dictionary-key");
 
   return (
     <div>

package/docs/ja/agent_skills.md

@@ -0,0 +1,53 @@
+---
+createdAt: 2026-02-09
+updatedAt: 2026-02-09
+title: エージェントスキル
+description: Intlayerエージェントスキルを使用して、AIエージェントのプロジェクト理解を向上させる方法を学びます。
+keywords:
+  - Intlayer
+  - エージェントスキル
+  - AIエージェント
+  - 国際化
+  - ドキュメンテーション
+slugs:
+  - doc
+  - agent_skills
+history:
+  - version: 8.0.4
+    date: 2026-02-09
+    changes: 履歴の初期化
+---
+
+## `intlayer init skills` コマンド
+
+`intlayer init skills` コマンドは、プロジェクトにエージェントスキルをセットアップする最も簡単な方法です。環境を検出し、好みのプラットフォームに必要な設定ファイルをインストールします。
+
+```bash
+npx intlayer init skills
+```
+
+このコマンドを実行すると、以下のことが行われます：
+
+1.  使用しているフレームワーク（Next.js、React、Viteなど）を検出します。
+2.  どのプラットフォーム（Cursor、VS Code、OpenCode、Claude Codeなど）のスキルをインストールするか尋ねます。
+3.  必要な設定ファイル（`.cursor/mcp.json`、`.vscode/mcp.json`、または `.intlayer/skills/*.md` など）を生成します。
+
+## サポートされているプラットフォーム
+
+Intlayerは以下のプラットフォームとの統合をサポートしています：
+
+### 1. Cursor
+
+CursorはMCP（Model Context Protocol）サーバーをサポートしています。`intlayer init skills` を実行すると、CursorがIntlayer MCPサーバーと通信できるようにするための `.cursor/mcp.json` ファイルが作成されます。
+
+### 2. VS Code
+
+VS Codeユーザー、特にGitHub Copilotやその他のMCP互換拡張機能を使用しているユーザー向けに、このコマンドは `.vscode/mcp.json` 設定を作成します。
+
+### 3. OpenCode
+
+OpenCodeは、ソフトウェアエンジニアリングタスク向けに設計されたインタラクティブなCLIエージェントです。Intlayerは、OpenCodeが国際化タスクを支援するための特定のスキルを提供します。
+
+### 4. Claude Code
+
+Claude Codeは、生成された設定をデスクトップまたはCLI設定に追加することで、Intlayerスキルを使用するように構成できます。

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

@@ -86,6 +86,7 @@ npx intlayer doc translate
 - **`--temperature [temperature]`**: AIモデルの温度設定。
 - **`--api-key [apiKey]`**: AIサービス用のAPIキーを提供。
 - **`--application-context [applicationContext]`**: AI翻訳に追加のコンテキストを提供。
+- **`--data-serialization [dataSerialization]`**: IntlayerのAI機能に使用するデータシリアライズ形式。オプション: `json` (標準的で信頼性が高い), `toon` (トークン消費が少ないが、一貫性が低い)。
 - **`--custom-prompt [prompt]`**: 翻訳に使用する基本プロンプトをカスタマイズします。（注：ほとんどのユースケースでは、翻訳の挙動をより良く制御できるため、`--custom-instructions` オプションの使用が推奨されます。）
 
   > 例: `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/ja/cli/fill.md

@@ -126,6 +126,7 @@ Affected dictionary keys for processing: app, comp-test, hello-world, lang-switc
 - **`--api-key [apiKey]`**: AIサービス用の独自APIキーを提供。
 - **`--custom-prompt [prompt]`**: 翻訳指示用のカスタムプロンプトを提供。
 - **`--application-context [applicationContext]`**: AI翻訳に追加のコンテキストを提供。
+- **`--data-serialization [dataSerialization]`**: IntlayerのAI機能に使用するデータシリアライズ形式。オプション: `json` (標準的で信頼性が高い), `toon` (トークン消費が少ないが、一貫性が低い)。
 
   > 例: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
 

package/docs/ja/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: AI設定に `dataSerialization` を追加
   - version: 8.0.0
     date: 2026-01-22
     changes: Move `importMode` build configuration to `dictionary` configuration.
@@ -883,6 +886,13 @@ Intlayerは、柔軟性と選択肢を高めるために複数のAIプロバイ
   - _例_: `'https://api.openai.com/v1'`
   - _注意_: ローカルまたはカスタムのAI APIエンドポイントを指すために使用できます。
 
+- **dataSerialization**:
+  - _型_: `'json' | 'toon'`
+  - _デフォルト_: `'json'`
+  - _説明_: IntlayerのAI機能に使用するデータシリアライズ形式。
+  - _例_: `'toon'`
+  - _注_: `json`: 標準的で信頼性が高い。より多くのトークンを使用します。`toon`: トークン消費が少ないが、JSONほど一貫性がない。
+
 ### ビルド設定
 
 Intlayerがアプリケーションの国際化をどのように最適化しビルドするかを制御する設定。