@intlayer/docs 9.1.0 → 9.1.2

package/docs/it/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: Varianti
 description: Usa il campo di metadati variant nei file di contenuto Intlayer per dichiarare alternative di contenuto con nome o strutturate — test A/B, banner stagionali, testo con feature flag, record di CMS, contenuti specifici per utente — e passare dall'una all'altra a runtime senza modifiche al codice.
 keywords:
@@ -22,7 +22,13 @@ history:
     changes: "Rilascio della funzionalità delle varianti"
   - version: 9.1.0
     date: 2026-06-26
-    changes: "`variant` ora accetta una stringa o un oggetto — i precedenti `meta` / record dinamici si dichiarano come varianti oggetto"
+    changes: "`variant` ora accetta una stringa o un oggetto — i precedenti `meta` / record dinamici vengono dichiarati come varianti oggetto"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "Una variante dichiara solo le chiavi che sovrascrive; le varianti non dichiarate ricadono sulla voce predefinita"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "I provider accettano una prop `variant` ambientale; i selettori accettano una catena di preferenza ordinata"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### Varianti parziali
+
+Una variante dichiara **solo le chiavi che sovrascrive**; il resto viene ereditato dalla voce predefinita.
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "hero-banner",
+  variant: "summer",
+  content: {
+    headline: t({
+      en: "Build faster all summer",
+      fr: "Développez plus vite tout l'été",
+    }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```tsx
+useIntlayer("hero-banner", { variant: "summer" });
+// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` ereditato
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → la voce predefinita
+```
+
+Quindi aggiungi un file variante solo dove la formulazione differisce effettivamente. Una chiave si risolve in `null` solo quando dichiara varianti ma nessuna voce predefinita.
+
 ### Consumare varianti con nome
 
 #### Variante predefinita
@@ -464,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## Variante ambientale
+
+Alcune dimensioni di variante sono fisse per un'intera sessione: il tenant, il tipo di istituto, il livello di piano. Vengono risolte una sola volta e nessun componente dovrebbe doverle passare a mano.
+
+> Non incapsulare `useIntlayer` in un hook personalizzato per iniettarle. L'ottimizzazione in fase di build riscrive solo una chiamata letterale `useIntlayer("key")` importata dal pacchetto del framework, quindi nulla dietro un wrapper finisce nel bundle.
+
+Dichiara invece la variante una sola volta sul provider, esattamente come `locale`:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerServerProvider } from "next-intlayer/server";
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    export default async function Layout({ children, params }) {
+      const { locale } = await params;
+      const schoolType = await getSchoolType();
+
+      return (
+        <IntlayerServerProvider locale={locale} variant={schoolType}>
+          <IntlayerClientProvider locale={locale} variant={schoolType}>
+            {children}
+          </IntlayerClientProvider>
+        </IntlayerServerProvider>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { createApp } from "vue";
+    import { installIntlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    installIntlayer(app, { locale: "en", variant: schoolType });
+
+    app.mount("#app");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+Ogni lettura di dizionario sotto il provider si risolve ora con quella variante, e un selettore nel punto di chiamata vince sempre:
+
+```tsx
+useIntlayer("hero-banner");
+// → la variante del provider
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — sostituisce la variante del provider, non la estende
+```
+
+### Forme
+
+La prop `variant` accetta tre forme:
+
+| Forma                                                     | Significato                             |
+| --------------------------------------------------------- | --------------------------------------- |
+| `variant="school1"`                                       | una variante denominata per ogni chiave |
+| `variant={["school1", "default"]}`                        | una catena di preferenza ordinata       |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | una variante per chiave di dizionario   |
+
+#### Catena di preferenza
+
+Una catena viene percorsa da sinistra a destra tra le voci dichiarate da ciascuna chiave e vince la prima dichiarata. Quando nessuna è dichiarata, si usa la voce predefinita implicita, esattamente come per un valore singolo.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` non dichiara una voce `school1` ma dichiara `school2` → "school2"
+// una chiave che non dichiara nessuna delle due → la voce predefinita
+```
+
+Quindi `["black_friday", "summer"]` si legge come «black friday se questa chiave ne ha una, altrimenti summer, altrimenti predefinita». Le catene sono accettate anche nel punto di chiamata:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> Nota che questa è l'immagine speculare dell'array accettato dal **campo** `variant` di un file di contenuto: lì un array _dichiara_ una voce per elemento, qui le _consuma_ in ordine di priorità.
+
+#### Mappa per chiave
+
+Indirizza ogni chiave di dizionario separatamente. La voce riservata `default` copre tutte le chiavi non elencate:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> Su un provider un oggetto semplice è **sempre** letto come mappa per chiave, mai come variante oggetto: le due sono strutturalmente identiche. Per fissare una variante oggetto a livello globale, annidala sotto una voce: `variant={{ default: { id: "prod_abc" } }}`.
+
+Poiché le chiavi della mappa sono verificate rispetto alle chiavi di dizionario dichiarate, un refuso — o una variante oggetto scritta direttamente, come `variant={{ id: "prod_abc" }}` — è un errore di compilazione.
+
 ## Modalità di caricamento
 
 Le varianti oggetto sono spesso caricate in modo differito. Imposta `importMode` sul dizionario per controllarlo:

package/docs/ja/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: バリアント
 description: Intlayer のコンテンツファイルで variant メタデータフィールドを使用し、名前付きまたは構造化されたコンテンツの代替（A/B テスト、季節バナー、フィーチャーフラグ付きコピー、CMS レコード、ユーザー固有コンテンツ）を宣言し、コード変更なしにランタイムで切り替えます。
 keywords:
@@ -22,7 +22,13 @@ history:
     changes: "バリアント機能のリリース"
   - version: 9.1.0
     date: 2026-06-26
-    changes: "`variant` が文字列またはオブジェクトを受け取るようになりました — 旧 `meta` / 動的レコードはオブジェクトバリアントとして宣言します"
+    changes: "`variant`は文字列またはオブジェクトを受け付けるようになりました — 以前の `meta` / 動的レコードはオブジェクトバリアントとして宣言されます"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "バリアントは上書きするキーのみを宣言します。宣言されていないバリアントはデフォルトのエントリにフォールバックします"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "プロバイダーがアンビエントな `variant` プロパティを受け取り、セレクターが順序付きの優先チェーンを受け取れるようになりました"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### 部分的なバリアント
+
+バリアントは**上書きするキーのみを宣言します**。残りはデフォルトのエントリから継承されます。
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "hero-banner",
+  variant: "summer",
+  content: {
+    headline: t({
+      en: "Build faster all summer",
+      fr: "Développez plus vite tout l'été",
+    }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```tsx
+useIntlayer("hero-banner", { variant: "summer" });
+// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` は継承されます
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → デフォルトのエントリ
+```
+
+したがって、実際にテキストが異なる場所にのみバリアントファイルを追加します。バリアントを宣言しているがデフォルトのエントリがない場合にのみ、キーは `null` に解決されます。
+
 ### 名前付きバリアントの利用
 
 #### デフォルトバリアント
@@ -464,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## アンビエントバリアント
+
+バリアントの次元の中には、テナント、学校種別、プラン階層のように、セッション全体で固定されるものがあります。これらは一度だけ解決されるものであり、各コンポーネントが手で渡すべきものではありません。
+
+> これらを注入するために `useIntlayer` を独自のフックでラップしないでください。ビルド時の最適化は、フレームワークパッケージからインポートされたリテラルな `useIntlayer("key")` の呼び出しだけを書き換えるため、ラッパーの背後にあるものはバンドルされません。
+
+代わりに、`locale` とまったく同じように、プロバイダーで一度だけバリアントを宣言します:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerServerProvider } from "next-intlayer/server";
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    export default async function Layout({ children, params }) {
+      const { locale } = await params;
+      const schoolType = await getSchoolType();
+
+      return (
+        <IntlayerServerProvider locale={locale} variant={schoolType}>
+          <IntlayerClientProvider locale={locale} variant={schoolType}>
+            {children}
+          </IntlayerClientProvider>
+        </IntlayerServerProvider>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { createApp } from "vue";
+    import { installIntlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    installIntlayer(app, { locale: "en", variant: schoolType });
+
+    app.mount("#app");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+これでプロバイダー配下のすべての辞書の読み取りがそのバリアントで解決され、呼び出し側のセレクターが常に優先されます:
+
+```tsx
+useIntlayer("hero-banner");
+// → プロバイダーのバリアント
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — プロバイダーのバリアントを置き換えます（拡張はしません）
+```
+
+### 形式
+
+`variant` プロパティは 3 つの形式を受け取ります:
+
+| 形式                                                      | 意味                                          |
+| --------------------------------------------------------- | --------------------------------------------- |
+| `variant="school1"`                                       | すべてのキーに対する 1 つの名前付きバリアント |
+| `variant={["school1", "default"]}`                        | 順序付きの優先チェーン                        |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | 辞書キーごとに 1 つのバリアント               |
+
+#### 優先チェーン
+
+チェーンは各キーが宣言しているエントリーに対して左から右へ順に試され、最初に宣言されているものが採用されます。どれも宣言されていない場合は、単一の値のときとまったく同じく、暗黙のデフォルトエントリーが使われます。
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` は `school1` エントリーを宣言していないが `school2` を宣言している → "school2"
+// どちらも宣言していないキー → デフォルトエントリー
+```
+
+したがって `["black_friday", "summer"]` は「このキーに black friday があればそれ、なければ summer、それもなければデフォルト」と読めます。チェーンは呼び出し側でも使えます:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> これはコンテンツファイルの `variant` **フィールド**が受け取る配列とちょうど逆であることに注意してください。あちらでは配列が要素ごとに 1 つのエントリーを*宣言*しますが、こちらでは優先順位に従ってそれらを*消費*します。
+
+#### キーごとのマップ
+
+辞書キーごとに個別に指定します。予約された `default` エントリーが、記載されていないすべてのキーをカバーします:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> プロバイダーでは、プレーンなオブジェクトは**常に**キーごとのマップとして読み取られ、オブジェクトバリアントとしては解釈されません（両者は構造的に同一のためです）。オブジェクトバリアントをグローバルに指定するには、エントリーの下にネストしてください: `variant={{ default: { id: "prod_abc" } }}`。
+
+マップのキーは宣言済みの辞書キーと照合されるため、タイプミス（あるいは `variant={{ id: "prod_abc" }}` のようにオブジェクトバリアントを直接書いた場合）はコンパイルエラーになります。
+
 ## 読み込みモード
 
 オブジェクトバリアントはしばしば遅延読み込みされます。これを制御するには辞書に `importMode` を設定します: