Dokumentacja konfiguracji Intlayer

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";
import { syncJSON } from "@intlayer/sync-json-plugin";
import { z } from "zod";

/**
 * Przykład pliku konfiguracyjnego Intlayer pokazujący wszystkie dostępne opcje.
 */
const config: IntlayerConfig = {
  /**
   * Konfiguracja ustawień internacjonalizacji.
   */
  internationalization: {
    /**
     * Lista obsługiwanych lokali w aplikacji.
     * Domyślnie: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * Lista wymaganych lokali, które muszą być zdefiniowane w każdym słowniku.
     * Jeśli pusta, wszystkie locale są wymagane w trybie `strict`.
     * Domyślnie: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * Poziom rygoru dla treści zinternacjonalizowanej.
     * - "strict": Błąd, jeśli brakuje zadeklarowanych lokali lub używane są niezadeklarowane locale.
     * - "inclusive": Ostrzeżenia, jeśli brakuje zadeklarowanych lokali.
     * - "loose": Akceptuje każde istniejące locale.
     * Domyślnie: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * Domyślne locale używane jako zapasowe, gdy żądane locale nie zostanie znalezione.
     * Domyślnie: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * Ustawienia kontrolujące operacje na słownikach i zachowanie zapasowe.
   */
  dictionary: {
    /**
     * Kontroluje sposób importowania słowników.
     * - "static": Importowane statycznie w czasie budowania.
     * - "dynamic": Importowane dynamicznie za pomocą Suspense.
     * - "fetch": Pobierane dynamicznie przez API Live Sync.
     * Domyślnie: "static"
     */
    importMode: "static",

    /**
     * Strategia automatycznego uzupełniania brakujących tłumaczeń za pomocą AI.
     * Może być wartością logiczną lub wzorcem ścieżki do zapisywania uzupełnionej treści.
     * Domyślnie: true
     */
    fill: true,

    /**
     * Fizyczna lokalizacja plików słowników.
     * - "local": Przechowywane w lokalnym systemie plików.
     * - "remote": Przechowywane w Intlayer CMS.
     * - "hybrid": Przechowywane zarówno lokalnie, jak i w Intlayer CMS.
     * - "plugin" (lub dowolny ciąg znaków): Dostarczane przez wtyczkę lub niestandardowe źródło.
     * Domyślnie: "local"
     */
    location: "local",

    /**
     * Czy automatycznie przekształcać treść (np. Markdown do HTML).
     * Domyślnie: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Konfiguracja routingu i middleware.
   */
  routing: {
    /**
     * Strategia routingu lokali.
     * - "prefix-no-default": Prefiks dla wszystkich języków z wyjątkiem domyślnego (np. /dashboard, /fr/dashboard).
     * - "prefix-all": Prefiks dla wszystkich języków (np. /en/dashboard, /fr/dashboard).
     * - "no-prefix": Locale nie jest widoczne w adresie URL.
     * - "search-params": Użycie ?locale=...
     * Domyślnie: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * Włącza proxy routingu lokalizacji Intlayer (middleware).
     * Obsługuje wykrywanie lokalizacji, przekierowania i przepisywanie w dev, preview i SSR.
     * - nieustawione (auto): serwery dev i preview utrzymują routing sterowany adresem URL,
     *   ignorując lokalizację zapisaną w ciasteczkach i nagłówkach. Prefiksy nadal są
     *   rozwiązywane, lokalizacja nadal jest zapisywana, a wykrywanie Accept-Language
     *   nadal działa. W produkcji zachowuje się jak `true`.
     * - true: pełne zachowanie w każdym środowisku.
     * - false: brak routingu lokalizacji.
     * Domyślnie: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * Miejsce przechowywania locale wybranego przez użytkownika.
     * Opcje: 'cookie', 'localStorage', 'sessionStorage', 'header' lub ich tablica.
     * Domyślnie: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * Bazowa ścieżka dla adresów URL aplikacji.
     * Domyślnie: ""
     */
    basePath: "",

    /**
     * Własne reguły przepisywania URL dla określonych ścieżek zlokalizowanych.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * Mapuje locale na nazwy hostów domen dla routingu opartego na domenach.
     * Adresy URL dla tych lokali będą absolutne (np. https://intlayer.cn/).
     * Domena implikuje locale, więc do ścieżki nie jest dodawany żaden prefiks locale.
     * Domyślnie: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * Ustawienia wyszukiwania i przetwarzania plików treści.
   */
  content: {
    /**
     * Rozszerzenia plików do skanowania w poszukiwaniu słowników.
     * Domyślnie: ['.content.ts', '.content.js', '.content.json' itp.]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * Katalogi, w których znajdują się pliki .content.
     * Domyślnie: ["."]
     */
    contentDir: ["src"],

    /**
     * Katalog kodu źródłowego.
     * Używany do optymalizacji budowania i przekształceń kodu.
     * Domyślnie: ["."]
     */
    codeDir: ["src"],

    /**
     * Wzorce do wykluczenia ze skanowania.
     * Domyślnie: ['node_modules', '.intlayer' itp.]
     */
    excludedPath: ["node_modules"],

    /**
     * Czy śledzić zmiany i regenerować słowniki podczas deweloperki.
     * Domyślnie: true w trybie deweloperskim
     */
    watch: true,

    /**
     * Polecenie do formatowania nowo utworzonych / zaktualizowanych plików .content.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * Konfiguracja edytora wizualnego.
   */
  editor: {
    /**
     * Czy edytor wizualny jest włączony.
     * Domyślnie: false
     */
    enabled: true,

    /**
     * URL Twojej aplikacji do walidacji źródła.
     * Domyślnie: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * Port lokalnego serwera edytora.
     * Domyślnie: 8000
     */
    port: 8000,

    /**
     * Publiczny URL edytora.
     * Domyślnie: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * URL Intlayer CMS.
     * Domyślnie: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * URL serwera API backendu.
     * Domyślnie: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * Czy włączyć synchronizację treści w czasie rzeczywistym.
     * Domyślnie: false
     */
    liveSync: true,
  },

  /**
   * Konfiguracja analityki (analytics).
   */
  analytics: {
    /**
     * Czy zbieranie danych analitycznych jest włączone (odsłony strony, ekspozycje treści, zdarzenia A/B).
     * Wymaga zainstalowanego pakietu `@intlayer/analytics` oraz ustawienia `editor.clientId` na potrzeby atrybucji.
     * Domyślnie: true
     */
    enabled: true,

    /**
     * Milisekundy między automatycznymi zbiorczymi wysyłkami do backendu.
     * Domyślnie: 20000
     */
    flushInterval: 20000,

    /**
     * Ułamek sesji do rejestrowania, od 0 (brak) do 1 (wszystkie).
     * Domyślnie: 1
     */
    sampleRate: 1,
  },

  /**
   * Ustawienia tłumaczenia i generowania opartego na AI.
   */
  ai: {
    /**
     * Wybrany dostawca AI.
     * Opcje: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * Domyślnie: 'openai'
     */
    provider: "openai",

    /**
     * Model dostawcy do użycia.
     */
    model: "gpt-4o",

    /**
     * Klucz API dostawcy.
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * Globalny kontekst ułatwiający AI generowanie tłumaczeń.
     */
    applicationContext: "To jest aplikacja do rezerwacji podróży.",

    /**
     * Bazowy URL dla API AI.
     */
    baseURL: "http://localhost:3000",

    /**
     * Serializacja danych (Data Serialization)
     *
     * Opcje:
     * - "json": domyślnie, niezawodna; zużywa więcej tokenów.
     * - "toon": szybciej, mniej tokenów, mniej spójna niż JSON.
     *
     * Domyślnie: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Ustawienia budowania i optymalizacji.
   */
  build: {
    /**
     * Tryb wykonywania budowania.
     * - "auto": Automatyczne budowanie podczas budowania (build time) aplikacji.
     * - "manual": Wymaga jawnego polecenia budowania.
     * Domyślnie: "auto"
     */
    mode: "auto",

    /**
     * Czy optymalizować wynikowy pakiet poprzez usuwanie nieużywanych słowników.
     * Domyślnie: true w środowisku produkcyjnym
     */
    optimize: true,

    /**
     * Minimalizuj słowniki, aby zmniejszyć rozmiar bundle'a.
     * Domyślnie: false
     *
     * Uwaga:
     * - Ta opcja zostanie zignorowana, jeśli `optimize` jest wyłączone.
     * - Ta opcja zostanie zignorowana, jeśli `editor.enabled` jest ustawione na true.
     */
    minify: true,

    /**
     * Usuń nieużywane klucze w słownikach.
     * Domyślnie: false
     *
     * Uwaga:
     * - Ta opcja zostanie zignorowana, jeśli `optimize` jest wyłączone.
     */
    purge: true,

    /**
     * Grupuj fragmenty słownika dla poszczególnych języków według granicy podziału
     * kodu, która ich używa, aby leniwie ładowana strona pobierała swoją treść w
     * jednym żądaniu.
     * Domyślnie: true
     *
     * Uwaga:
     * - Dotyczy tylko słowników używających `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * Ładuj słownik razem z fragmentem, który go używa, zamiast pobierać go po
     * wyrenderowaniu tego fragmentu. Odczyty renderują się synchronicznie zamiast
     * zawieszać, więc nawigacja nie miga już stanem ładowania.
     * Domyślnie: true
     *
     * Uwaga:
     * - Oczekiwany jest tylko rozwiązany język, więc strona pobiera wyłącznie
     *   język, który wyświetla.
     */
    dictionariesPreload: true,

    /**
     * Format wyjściowy generowanych plików słowników.
     * Domyślnie: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * Czy przeprowadzać sprawdzanie typów TypeScript podczas budowania (build time).
     * Domyślnie: false
     */
    checkTypes: false,
  },

  /**
   * Konfiguracja loggera.
   */
  log: {
    /**
     * Tryb logowania.
     * - "default": Standardowe logowanie.
     * - "verbose": Szczegółowe logowanie do debugowania.
     * - "disabled": Wyłącz logowanie.
     * Domyślnie: "default"
     */
    mode: "default",

    /**
     * Prefiks dla wszystkich wiadomości w logach.
     * Domyślnie: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * Konfiguracja systemowa (do zaawansowanych zastosowań)
   */
  system: {
    /**
     * Katalog, w którym przechowywane są zlokalizowane słowniki.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * Katalog dla module augmentation.
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * Katalog dla niepołączonych słowników.
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * Katalog typów słowników.
     */
    typesDir: ".intlayer/types",

    /**
     * Katalog głównych plików aplikacji.
     */
    mainDir: ".intlayer/main",

    /**
     * Katalog skompilowanych plików konfiguracyjnych.
     */
    configDir: ".intlayer/config",

    /**
     * Katalog plików cache.
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * Konfiguracja kompilatora (do zaawansowanych zastosowań)
   */
  compiler: {
    /**
     * Czy kompilator jest włączony.
     *
     * - false: wyłącz kompilator.
     * - true: włącz kompilator.
     * - "build-only": pomiń kompilator podczas deweloperki dla szybszego startu.
     *
     * Domyślnie: false
     */
    enabled: true,

    /**
     * Definiuje ścieżkę do pliku wyjściowego. Zastępuje `outputDir`.
     *
     * - Ścieżki `./` są rozwiązywane względem katalogu komponentu.
     * - Ścieżki `/` są rozwiązywane względem katalogu bazowego projektu (`baseDir`).
     *
     * - Obecność zmiennej `{{locale}}` w ścieżce wyzwala generowanie osobnych słowników na język.
     *
     * Przykłady:
     * ```ts
     * {
     *   // Tworzy wielojęzyczne pliki .content.ts obok komponentu
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // To samo poprzez ciąg szablonowy
     * }
     * ```
     *
     * ```ts
     * {
     *   // Tworzy scentralizowane pliki JSON na język w korzeniu projektu
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // To samo poprzez ciąg szablonowy
     * }
     * ```
     *
     * Lista zmiennych:
     *   - `fileName`: Nazwa pliku.
     *   - `key`: Klucz treści.
     *   - `locale`: Locale treści.
     *   - `extension`: Rozszerzenie pliku.
     *   - `componentFileName`: Nazwa pliku komponentu.
     *   - `componentExtension`: Rozszerzenie pliku komponentu.
     *   - `format`: Format słownika.
     *   - `componentFormat`: Format słownika komponentu.
     *   - `componentDirPath`: Ścieżka do katalogu komponentu.
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * Czy zapisać komponenty po ich przekształceniu.
     * W ten sposób można uruchomić kompilator raz, aby przekształcić aplikację, a następnie go usunąć.
     */
    saveComponents: false,

    /**
     * Pozostaw tylko treść w wygenerowanym pliku. Przydatne dla formatów i18next lub ICU MessageFormat JSON na język.
     */
    noMetadata: false,

    /**
     * Prefiks klucza słownika
     */
    dictionaryKeyPrefix: "", // Dodaje opcjonalny prefiks do wyodrębnionych kluczy słownika
  },

  /**
   * Własne schematy do walidacji struktury słowników.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * Konfiguracja słownika.
   */
  dictionary: {
    /**
     * Kontroluje sposób importowania słowników.
     * - "static": Importowane statycznie podczas budowania.
     * - "dynamic": Importowane dynamicznie przy użyciu Suspense.
     * - "fetch": Pobierane dynamicznie przez API synchronizacji na żywo.
     */
    importMode: "static",

    /**
     * Domyślny format komunikatów dla wszystkich słowników w projekcie.
     * - 'intlayer': Natywny format intlayer (domyślny).
     * - 'icu': Format komunikatów ICU.
     * - 'i18next': Format i18next.
     * - 'vue-i18n': Format Vue I18n.
     * - 'po': Format GNU Gettext PO.
     */
    format: "icu",
  },

  /**
   * Konfiguracja wtyczek.
   */
  plugins: [
    syncJSON({
      format: "icu",
      source: ({ locale }) => `./messages/${locale}.json`,
    }),
  ],
};

export default config;

routing: {
  mode: "prefix-no-default", // Strategia zapasowa
  rewrite: nextjsRewrite({
    "/about": {
      en: "/about",
      fr: "/a-propos",
    },
    "/product/[slug]": {
      en: "/product/[slug]",
      fr: "/produit/[slug]",
    },
    "/blog/[category]/[id]": {
      en: "/blog/[category]/[id]",
      fr: "/journal/[category]/[id]",
    },
  }),
}

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage",
        name: "user-locale",
      },
      {
        type: "cookie",
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "search-params",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "no-prefix",
    storage: {
      type: "sessionStorage",
      name: "app-locale",
    },
    basePath: "/my-app",
  },
};

export default config;

// intlayer.config.ts
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // Rezerwowa strategia dla nieprzepisanych ścieżek
    storage: "cookie",
    rewrite: nextjsRewrite({
      "/about": {
        en: "/about",
        fr: "/a-propos",
      },
      "/product/[slug]": {
        en: "/product/[slug]",
        fr: "/produit/[slug]",
      },
      "/blog/[category]/[id]": {
        en: "/blog/[category]/[id]",
        fr: "/journal/[category]/[id]",
      },
    }),
  },
};

export default config;

dictionary: {
  fill: {
    en: "/locales/en/{{key}}.content.json",
    fr: ({ key }) => `/locales/fr/${key}.content.json`,
    es: false,
  },
};