@intlayer/docs 7.2.3 → 7.3.0

package/docs/it/cli/push.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Push Dizionari
+description: Scopri come inviare i tuoi dizionari all'editor e CMS di Intlayer.
+keywords:
+  - Push
+  - Dizionari
+  - CLI
+  - Intlayer
+  - Editor
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - push
+---
+
+# Push Dizionari
+
+```bash
+npx intlayer dictionary push
+```
+
+Se l'[editor di Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md) è installato, puoi anche inviare i dizionari all'editor. Questo comando permette di rendere i dizionari disponibili all'[editor](https://intlayer.org/dashboard). In questo modo, puoi condividere i tuoi dizionari con il tuo team e modificare i contenuti senza dover modificare il codice della tua applicazione.
+
+## Alias:
+
+- `npx intlayer dictionaries push`
+- `npx intlayer dictionary push`
+- `npx intlayer dic push`
+
+## Argomenti:
+
+**Opzioni del dizionario:**
+
+- **`-d`, `--dictionaries`**: ID dei dizionari da inviare. Se non specificato, verranno inviati tutti i dizionari.
+
+  > Esempio: `npx intlayer dictionary push -d my-dictionary-id my-other-dictionary-id`
+
+- **`--dictionary`**: ID dei dizionari da inviare (alias di --dictionaries).
+
+  > Esempio: `npx intlayer dictionary push --dictionary my-dictionary-id my-other-dictionary-id`
+
+**Opzioni di configurazione:**
+
+- **`--base-dir`**: Specifica la directory base del progetto. Per recuperare la configurazione di intlayer, il comando cercherà il file `intlayer.config.{ts,js,json,cjs,mjs}` nella directory base.
+
+  > Esempio: `npx intlayer dictionary push --env-file .env.production.local`
+
+- **`--no-cache`**: Disabilita la cache.
+
+  > Esempio: `npx intlayer build --no-cache`
+
+**Opzioni per le variabili d'ambiente:**
+
+- **`--env`**: Specifica l'ambiente (es. `development`, `production`). Utile nel caso in cui si utilizzino variabili d'ambiente nel file di configurazione di intlayer.
+- **`--env-file`**: Fornisce un file di ambiente personalizzato da cui caricare le variabili. Utile nel caso in cui si utilizzino variabili d'ambiente nel file di configurazione di intlayer.
+
+  > Esempio: `npx intlayer dictionary push --env-file .env.production.local`
+
+  > Esempio: `npx intlayer dictionary push --env production`
+
+**Opzioni di output:**
+
+- **`-r`, `--delete-locale-dictionary`**: Salta la domanda che chiede di eliminare le directory delle localizzazioni una volta che i dizionari sono stati inviati, e le rimuove. Per impostazione predefinita, se il dizionario è definito localmente, sovrascriverà il contenuto dei dizionari remoti.
+
+  > Esempio: `npx intlayer dictionary push -r`
+
+  > Esempio: `npx intlayer dictionary push --delete-locale-dictionary`
+
+- **`-k`, `--keep-locale-dictionary`**: Salta la domanda che chiede di eliminare le directory delle localizzazioni una volta che i dizionari sono stati inviati, e le mantiene. Per impostazione predefinita, se il dizionario è definito localmente, sovrascriverà il contenuto dei dizionari remoti.
+
+  > Esempio: `npx intlayer dictionary push -k`
+
+  > Esempio: `npx intlayer dictionary push --keep-locale-dictionary`
+
+**Opzioni di preparazione:**
+
+- **`--build`**: Costruisce i dizionari prima di inviarli per assicurarsi che il contenuto sia aggiornato. True forza la build, false la salta, undefined permette di usare la cache della build.
+
+**Opzioni di log:**
+
+- **`--verbose`**: Abilita il logging dettagliato per il debug. (default a true usando la CLI)
+
+**Opzioni Git:**
+
+- **`--git-diff`**: Esegue solo sui dizionari che includono modifiche dalla base (default `origin/main`) al ramo corrente (default: `HEAD`).
+- **`--git-diff-base`**: Specifica il riferimento base per il git diff (default `origin/main`).
+- **`--git-diff-current`**: Specifica il riferimento corrente per il git diff (default: `HEAD`).
+- **`--uncommitted`**: Include le modifiche non committate.
+- **`--unpushed`**: Include le modifiche non pushate.
+- **`--untracked`**: Include i file non tracciati.
+
+  > Esempio: `npx intlayer dictionary push --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Esempio: `npx intlayer dictionary push --uncommitted --unpushed --untracked`

package/docs/it/cli/sdk.md

@@ -0,0 +1,67 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: SDK CLI
+description: Scopri come utilizzare l'SDK CLI di Intlayer nel tuo codice.
+keywords:
+  - SDK
+  - CLI
+  - Intlayer
+  - Programmatico
+slugs:
+  - doc
+  - concept
+  - cli
+  - sdk
+---
+
+# SDK CLI
+
+L'SDK CLI è una libreria che ti permette di utilizzare la CLI di Intlayer nel tuo codice.
+
+```bash packageManager="npm"
+npm install @intlayer/cli --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/cli --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/cli --save-dev
+```
+
+Esempio di utilizzo:
+
+```ts
+import {
+  push,
+  pull,
+  fill,
+  build,
+  listContentDeclaration,
+  testMissingTranslations,
+  docTranslate,
+  docReview,
+  transform,
+} from "@intlayer/cli";
+
+push();
+// ...
+pull();
+// ...
+fill();
+// ...
+build();
+// ...
+listContentDeclaration();
+// ...
+testMissingTranslations();
+// ...
+docTranslate();
+// ...
+docReview();
+// ...
+transform();
+// ...
+```

package/docs/it/cli/test.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Test delle traduzioni mancanti
+description: Scopri come testare e identificare le traduzioni mancanti nei tuoi dizionari.
+keywords:
+  - Test
+  - Traduzioni Mancanti
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - test
+---
+
+# Test delle traduzioni mancanti
+
+```bash
+npx intlayer content test
+```
+
+## Alias:
+
+- `npx intlayer test`
+
+Questo comando analizza i tuoi file di dichiarazione dei contenuti per identificare le traduzioni mancanti in tutte le localizzazioni configurate. Fornisce un report completo che mostra quali chiavi di traduzione mancano per quali localizzazioni, aiutandoti a mantenere la coerenza nei tuoi contenuti multilingue.
+
+## Esempio di output:
+
+```bash
+pnpm intlayer content test
+Traduzioni mancanti:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locali: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Locali richieste: en
+Locali mancanti: pl, tr, es
+Locali richieste mancanti: -
+Totale locali mancanti: 3
+Totale locali richieste mancanti: 0
+```
+
+## Argomenti:
+
+**Opzioni di configurazione:**
+
+- **`--env`**: Specifica l'ambiente (es. `development`, `production`).
+- **`--env-file [envFile]`**: Fornisce un file ambiente personalizzato da cui caricare le variabili.
+- **`--base-dir`**: Specifica la directory base per il progetto.
+
+  > Esempio: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**: Disabilita la cache.
+
+  > Esempio: `npx intlayer build --no-cache`
+
+**Opzioni di preparazione:**
+
+- **`--build`**: Costruisce i dizionari prima del push per assicurarsi che il contenuto sia aggiornato. True forza la build, false la salta, undefined permette di usare la cache della build.
+
+**Opzioni di log:**
+
+- **`--verbose`**: Abilita il logging dettagliato per il debug. (default a true usando la CLI)
+
+  > Esempio: `npx intlayer content test --verbose`
+
+## Esempio:
+
+```bash
+npx intlayer content test --verbose
+```
+
+L'output ti aiuta a identificare rapidamente quali traduzioni devono essere completate per garantire che la tua applicazione funzioni correttamente in tutte le localizzazioni configurate.

package/docs/it/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Trasformare Componenti
+description: Scopri come trasformare componenti esistenti per utilizzare Intlayer.
+keywords:
+  - Trasformare
+  - Componenti
+  - Migrazione
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# Trasformare componenti
+
+```bash
+npx intlayer transform
+```
+
+Questo comando analizza i tuoi file di codice per aiutarti a migrare componenti esistenti all'uso di Intlayer. Supporta la selezione interattiva dei file o il targeting di file specifici.
+
+## Alias:
+
+- `npx intlayer trans`
+
+## Argomenti:
+
+**Opzioni di selezione file:**
+
+- **`-f, --file [files...]`**: Elenco di file specifici da trasformare. Se non fornito, la CLI cercherà i file corrispondenti (`**/*.{tsx,jsx,vue,svelte,ts,js}`) e ti chiederà di selezionare quali trasformare.
+
+  > Esempio: `npx intlayer transform -f src/components/MyComponent.tsx`
+
+**Opzioni di output:**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**: Directory in cui salvare i file di dichiarazione dei contenuti generati.
+
+  > Esempio: `npx intlayer transform -o src/content`
+
+- **`--code-only`**: Trasforma solo il codice del componente (non scrivere la dichiarazione dei contenuti).
+
+  > Esempio: `npx intlayer transform --code-only`
+
+- **`--declaration-only`**: Genera solo la dichiarazione dei contenuti (non riscrivere il componente).
+
+  > Esempio: `npx intlayer transform --declaration-only`
+
+**Opzioni di configurazione:**
+
+- **`--base-dir`**: Specifica la directory base per il progetto.
+- **`--env`**: Specifica l'ambiente.
+- **`--env-file`**: Fornisci un file di ambiente personalizzato.
+- **`--verbose`**: Abilita il logging dettagliato.
+
+**Plugin richiesti:**
+
+Il comando transform funziona senza plugin aggiuntivi per file TypeScript / JSX. Tuttavia, richiede l'installazione dei seguenti plugin per i progetti Vue e Svelte:
+
+- **`@intlayer/vue-transformer`**: Per i file Vue.
+- **`@intlayer/svelte-transformer`**: Per i file Svelte.

package/docs/it/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Controllare la versione della CLI
+description: Scopri come verificare la versione della CLI Intlayer installata.
+keywords:
+  - Versione
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# Controllare la versione della CLI
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+Entrambi i comandi mostrano la versione della CLI Intlayer installata.

package/docs/it/cli/watch.md

@@ -0,0 +1,39 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Osservare i Dizionari
+description: Scopri come osservare le modifiche nei tuoi file di dichiarazione dei contenuti e costruire automaticamente i dizionari.
+keywords:
+  - Osservare
+  - Dizionari
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - watch
+---
+
+# Osservare i Dizionari
+
+```bash
+npx intlayer watch
+```
+
+Questo comando osserverà le modifiche nei tuoi file di dichiarazione dei contenuti e costruirà i dizionari nella directory `.intlayer`.
+Questo comando è l'equivalente di `npx intlayer build --watch --skip-prepare`.
+
+## Alias:
+
+- `npx intlayer dictionaries watch`
+- `npx intlayer dictionary watch`
+- `npx intlayer dic watch`
+
+## Argomenti:
+
+- **`--with`**: Avvia un comando in parallelo con l'osservazione.
+
+  > Esempio: `npx intlayer watch --with "next dev --turbopack"`
+
+  > Esempio: `npx intlayer watch --with "next dev --turbopack"`

package/docs/it/packages/intlayer/getPrefix.md

@@ -0,0 +1,211 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: Documentazione della funzione getPrefix | intlayer
+description: Scopri come utilizzare la funzione getPrefix per il pacchetto intlayer
+keywords:
+  - getPrefix
+  - prefisso
+  - Intlayer
+  - intlayer
+  - Internazionalizzazione
+  - Documentazione
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: Documentazione iniziale
+---
+
+# Documentazione: Funzione `getPrefix` in `intlayer`
+
+## Descrizione
+
+La funzione `getPrefix` determina il prefisso URL per una data locale basandosi sulla configurazione della modalità di routing. Confronta la locale con la locale predefinita e restituisce un oggetto contenente tre diversi formati di prefisso per una costruzione flessibile degli URL.
+
+**Caratteristiche principali:**
+
+- Prende una locale come primo parametro (obbligatorio)
+- Oggetto `options` opzionale con `defaultLocale` e `mode`
+- Restituisce un oggetto con le proprietà `prefix` e `localePrefix`
+- Supporta tutte le modalità di routing: `prefix-no-default`, `prefix-all`, `no-prefix` e `search-params`
+- Utility leggera per determinare quando aggiungere i prefissi di locale
+
+---
+
+## Firma della funzione
+
+```typescript
+getPrefix(
+  locale: Locales,               // Obbligatorio
+  options?: {                    // Opzionale
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): GetPrefixResult
+
+type GetPrefixResult = {
+  prefix: string;   // es. 'fr/' o ''
+  localePrefix?: Locale; // es. 'fr' o undefined
+}
+```
+
+---
+
+## Parametri
+
+- `locale: Locales`
+  - **Descrizione**: La locale per cui generare il prefisso. Se il valore è falsy (undefined, null, stringa vuota), la funzione restituisce una stringa vuota.
+  - **Tipo**: `Locales`
+  - **Obbligatorio**: Sì
+
+- `options?: object`
+  - **Descrizione**: Oggetto di configurazione per la determinazione del prefisso.
+  - **Tipo**: `object`
+  - **Obbligatorio**: No (Opzionale)
+
+  - `options.defaultLocale?: Locales`
+    - **Descrizione**: La locale predefinita per l'applicazione. Se non fornita, utilizza la locale predefinita configurata nel progetto.
+    - **Tipo**: `Locales`
+    - **Predefinito**: [`Configurazione del Progetto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Descrizione**: La modalità di routing URL per la gestione della locale. Se non fornita, utilizza la modalità configurata nella configurazione del progetto.
+    - **Tipo**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Predefinito**: [`Configurazione del Progetto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#middleware)
+    - **Modalità**:
+      - `prefix-no-default`: Restituisce stringhe vuote quando la locale corrisponde alla locale predefinita
+      - `prefix-all`: Restituisce il prefisso per tutte le località, inclusa quella predefinita
+      - `no-prefix`: Restituisce stringhe vuote (nessun prefisso negli URL)
+      - `search-params`: Restituisce stringhe vuote (locale nei parametri di query)
+
+### Ritorna
+
+- **Tipo**: `GetPrefixResult`
+- **Descrizione**: Un oggetto contenente tre diversi formati di prefisso:
+  - `prefix`: Il prefisso del percorso con slash finale (es. `'fr/'`, `''`)
+  - `localePrefix`: L'identificatore della locale senza slash (es. `'fr'`, `undefined`)
+
+---
+
+## Esempio di Utilizzo
+
+### Utilizzo Base
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// Controlla il prefisso per la locale inglese
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Restituisce: { prefix: 'en/', localePrefix: 'en' }
+
+// Controlla il prefisso per la locale francese
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Restituisce: { prefix: 'fr/', localePrefix: 'fr' }
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// Restituisce: { prefix: '', localePrefix: undefined }
+```
+
+### Modalità di Routing Differenti
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: Restituisce sempre il prefisso
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// Restituisce: { prefix: '/en', localePrefix: 'en' }
+
+// prefix-no-default: Nessun prefisso quando la locale corrisponde a quella di default
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Restituisce: { prefix: '', localePrefix: undefined }
+
+// prefix-no-default: Restituisce il prefisso quando la locale è diversa da quella predefinita
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Restituisce: { prefix: 'fr/', localePrefix: 'fr' }
+
+// no-prefix & search-params: Non restituisce mai il prefisso
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" });
+// Restituisce: { prefix: '', localePrefix: undefined }
+
+getPrefix(Locales.ENGLISH, { mode: "search-params" });
+// Restituisce: { prefix: '', localePrefix: undefined }
+```
+
+### Esempio Pratico
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// Costruisci URL con il prefisso appropriato per una specifica locale
+const locale = Locales.FRENCH;
+const { prefix, localePrefix } = getPrefix(locale, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+
+// Utilizzo del prefisso per la costruzione del percorso
+const url1 = `/${prefix}about`.replace(/\/+/g, "/");
+// Risultato: "/fr/about"
+
+// Utilizzo di localePrefix per l'identificazione della locale
+console.log(`Current locale: ${localePrefix}`);
+// Output: "Current locale: fr"
+```
+
+---
+
+## Funzioni Correlate
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getLocalizedUrl.md): Genera un URL localizzato per una specifica locale
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getMultilingualUrls.md): Genera URL per tutte le localizzazioni configurate
+
+---
+
+## TypeScript
+
+```typescript
+type GetPrefixResult = {
+  prefix: string; // Il prefisso del percorso con slash finale (es. 'fr/' o '')
+
+  localePrefix?: Locale; // L'identificatore della locale senza slash (es. 'fr' o undefined)
+};
+
+function getPrefix(
+  locale: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+  }
+): GetPrefixResult;
+```

package/docs/ja/cli/build.md

@@ -0,0 +1,78 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 辞書のビルド
+description: コンテンツ宣言ファイルからIntlayerの辞書をビルドする方法を学びます。
+keywords:
+  - ビルド
+  - 辞書
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - build
+---
+
+# 辞書のビルド
+
+辞書をビルドするには、以下のコマンドを実行します。
+
+```bash
+npx intlayer build
+```
+
+またはウォッチモードで
+
+```bash
+npx intlayer build --watch
+```
+
+このコマンドはデフォルトで `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}` にある宣言コンテンツファイルを検出し、`.intlayer` ディレクトリに辞書をビルドします。
+
+## エイリアス:
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+## 引数:
+
+- **`--base-dir`**: プロジェクトのベースディレクトリを指定します。intlayerの設定を取得するために、コマンドはベースディレクトリ内の `intlayer.config.{ts,js,json,cjs,mjs}` ファイルを探します。
+
+  > 例: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: 環境を指定します（例：`development`、`production`）。intlayerの設定ファイルで環境変数を使用している場合に便利です。
+
+  > 例: `npx intlayer build --env production`
+
+- **`--env-file`**: 変数を読み込むためのカスタム環境ファイルを指定します。intlayerの設定ファイルで環境変数を使用している場合に便利です。
+
+  > 例: `npx intlayer build --env-file .env.production.local`
+
+- **`--with`**: ビルドと並行してコマンドを開始します。
+
+- **`--base-dir`**: プロジェクトのベースディレクトリを指定します。intlayerの設定を取得するために、コマンドはベースディレクトリ内の `intlayer.config.{ts,js,json,cjs,mjs}` ファイルを探します。
+
+  > 例: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: 環境を指定します（例：`development`、`production`）。intlayerの設定ファイルで環境変数を使用している場合に便利です。
+
+  > 例: `npx intlayer build --env production`
+
+- **`--env-file`**: 変数を読み込むためのカスタム環境ファイルを指定します。intlayerの設定ファイルで環境変数を使用している場合に便利です。
+
+  > 例: `npx intlayer build --env-file .env.production.local`
+
+- **`--with`**: ビルドと並行してコマンドを開始します。
+
+  > 例: `npx intlayer build --with "next dev --turbopack"`
+
+- **`--skip-prepare`**: prepareステップをスキップします。
+
+  > 例: `npx intlayer build --skip-prepare`
+
+- **`--no-cache`**: キャッシュを無効にします。
+
+  > 例: `npx intlayer build --no-cache`