Dokumentasi Konfigurasi Intlayer

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

/**
 * Contoh file konfigurasi Intlayer yang menunjukkan semua opsi yang tersedia.
 */
const config: IntlayerConfig = {
  /**
   * Konfigurasi untuk pengaturan internasionalisasi.
   */
  internationalization: {
    /**
     * Daftar locale yang didukung dalam aplikasi.
     * Default: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * Daftar locale wajib yang harus ditentukan dalam setiap kamus (dictionary).
     * Jika kosong, semua locale wajib dalam mode `strict`.
     * Default: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * Tingkat ketatnya (strictness) konten yang diinternasionalisasi.
     * - "strict": Error jika ada locale yang dideklarasikan hilang atau tidak dideklarasikan.
     * - "inclusive": Peringatan jika locale yang dideklarasikan hilang.
     * - "loose": Menerima locale apa pun yang ada.
     * Default: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * Locale default yang digunakan sebagai cadangan (fallback) jika locale yang diminta tidak ditemukan.
     * Default: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * Pengaturan yang mengontrol operasi kamus dan perilaku fallback.
   */
  dictionary: {
    /**
     * Mengontrol bagaimana kamus diimpor.
     * - "static": Diimpor secara statis pada saat build.
     * - "dynamic": Diimpor secara dinamis menggunakan Suspense.
     * - "fetch": Diambil secara dinamis melalui API sinkronisasi langsung (live sync).
     * Default: "static"
     */
    importMode: "static",

    /**
     * Strategi untuk mengisi otomatis terjemahan yang hilang menggunakan AI.
     * Bisa berupa boolean atau pola path untuk menyimpan konten yang diisi.
     * Default: true
     */
    fill: true,

    /**
     * Lokasi fisik file kamus.
     * - "local": Disimpan di sistem file lokal.
     * - "remote": Disimpan di Intlayer CMS.
     * - "hybrid": Disimpan di sistem file lokal dan Intlayer CMS.
     * - "plugin" (atau string kustom lainnya): Disediakan oleh plugin atau sumber kustom.
     * Default: "local"
     */
    location: "local",

    /**
     * Apakah akan mengubah konten secara otomatis (misalnya, Markdown ke HTML).
     * Default: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Konfigurasi routing dan middleware.
   */
  routing: {
    /**
     * Strategi routing locale.
     * - "prefix-no-default": Prefiks untuk semua kecuali locale default (misalnya, /dashboard, /fr/dashboard).
     * - "prefix-all": Prefiks untuk semua locale (misalnya, /en/dashboard, /fr/dashboard).
     * - "no-prefix": Tidak ada locale di URL.
     * - "search-params": Gunakan ?locale=...
     * Default: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * Mengaktifkan proxy perutean locale Intlayer (middleware).
     * Menangani deteksi locale, pengalihan, dan penulisan ulang di dev, preview, dan SSR.
     * - tidak diatur (auto): server dev dan preview menjaga perutean tetap digerakkan URL
     *   dengan mengabaikan locale yang tersimpan di cookie dan header. Prefiks tetap
     *   diselesaikan, locale tetap disimpan, dan deteksi Accept-Language tetap berlaku.
     *   Di produksi berperilaku seperti `true`.
     * - true: perilaku penuh di setiap lingkungan.
     * - false: tanpa perutean locale.
     * Default: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * Tempat menyimpan locale yang dipilih pengguna.
     * Opsi: 'cookie', 'localStorage', 'sessionStorage', 'header', atau array dari opsi ini.
     * Default: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * Path dasar untuk URL aplikasi.
     * Default: ""
     */
    basePath: "",

    /**
     * Aturan penulisan ulang URL kustom untuk path spesifik locale.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * Memetakan locale ke nama host domain for routing berbasis domain.
     * URL untuk locale ini akan bersifat absolut (misalnya, https://intlayer.cn/).
     * Domain tersebut menyiratkan locale, sehingga tidak ada prefiks locale yang ditambahkan ke path.
     * Default: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * Pengaturan untuk menemukan dan memproses file konten.
   */
  content: {
    /**
     * Ekstensi file yang akan dipindai untuk kamus.
     * Default: ['.content.ts', '.content.js', '.content.json', dll.]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * Direktori tempat file .content berada.
     * Default: ["."]
     */
    contentDir: ["src"],

    /**
     * Direktori tempat kode sumber berada.
     * Digunakan untuk optimasi build dan transformasi kode.
     * Default: ["."]
     */
    codeDir: ["src"],

    /**
     * Pola yang akan dikecualikan dari pemindaian.
     * Default: ['node_modules', '.intlayer', dll.]
     */
    excludedPath: ["node_modules"],

    /**
     * Apakah akan memantau perubahan dan membangun ulang kamus dalam pengembangan.
     * Default: true dalam pengembangan
     */
    watch: true,

    /**
     * Perintah untuk memformat file .content yang baru dibuat/diperbarui.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * Konfigurasi Visual Editor.
   */
  editor: {
    /**
     * Apakah editor visual diaktifkan.
     * Default: false
     */
    enabled: true,

    /**
     * URL aplikasi Anda untuk validasi asal (origin).
     * Default: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * Port untuk server editor lokal.
     * Default: 8000
     */
    port: 8000,

    /**
     * URL publik untuk editor.
     * Default: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * URL Intlayer CMS.
     * Default: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * URL Back-end API.
     * Default: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * Apakah akan mengaktifkan sinkronisasi konten real-time.
     * Default: false
     */
    liveSync: true,
  },

  /**
   * Konfigurasi analitik (analytics).
   */
  analytics: {
    /**
     * Apakah pengumpulan analitik diaktifkan (tampilan halaman, eksposur konten, peristiwa A/B).
     * Membutuhkan `@intlayer/analytics` terpasang dan `editor.clientId` diatur agar atribusi berfungsi.
     * Default: true
     */
    enabled: true,

    /**
     * Milidetik antara pengiriman batch otomatis ke backend.
     * Default: 20000
     */
    flushInterval: 20000,

    /**
     * Fraksi sesi yang direkam, dari 0 (tidak ada) hingga 1 (semua).
     * Default: 1
     */
    sampleRate: 1,
  },

  /**
   * Pengaturan terjemahan dan pembuatan berbasis AI.
   */
  ai: {
    /**
     * Penyedia AI yang akan digunakan.
     * Opsi: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * Default: 'openai'
     */
    provider: "openai",

    /**
     * Model yang akan digunakan dari penyedia yang dipilih.
     */
    model: "gpt-4o",

    /**
     * Kunci API penyedia.
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * Konteks global untuk memandu AI dalam menghasilkan terjemahan.
     */
    applicationContext: "Ini adalah aplikasi pemesanan perjalanan.",

    /**
     * URL dasar untuk AI API.
     */
    baseURL: "http://localhost:3000",

    /**
     * Serialisasi data (Data serialization)
     *
     * Opsi:
     * - "json": Standar, andal; menggunakan lebih banyak token.
     * - "toon": Lebih sedikit token, kurang konsisten dibandingkan JSON.
     *
     * Default: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Pengaturan build dan optimasi.
   */
  build: {
    /**
     * Mode eksekusi build.
     * - "auto": Build otomatis selama build aplikasi.
     * - "manual": Memerlukan perintah build eksplisit.
     * Default: "auto"
     */
    mode: "auto",

    /**
     * Apakah akan mengoptimalkan bundel akhir dengan memangkas kamus yang tidak digunakan.
     * Default: true dalam produksi
     */
    optimize: true,

    /**
     * Minifikasikan kamus untuk mengurangi ukuran bundle.
     * Default: true
     *
     * Catatan:
     * - Opsi ini akan diabaikan jika `optimize` dinonaktifkan.
     * - Opsi ini akan diabaikan jika `editor.enabled` adalah true.
     */
    minify: true,

    /**
     * Bersihkan kunci yang tidak digunakan dalam kamus.
     * Default: true
     *
     * Catatan:
     * - Opsi ini akan diabaikan jika `optimize` dinonaktifkan.
     */
    purge: true,

    /**
     * Kelompokkan potongan kamus per lokal berdasarkan batas pemisahan kode yang
     * menggunakannya, sehingga halaman yang dimuat secara lazy mengambil kontennya
     * dalam satu permintaan.
     * Default: true
     *
     * Catatan:
     * - Hanya berlaku untuk kamus yang menggunakan `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * Muat kamus bersama potongan yang menggunakannya, alih-alih mengambilnya
     * setelah potongan tersebut dirender. Pembacaan dirender secara sinkron
     * alih-alih ditangguhkan, sehingga navigasi tidak lagi menampilkan kedipan
     * status pemuatan.
     * Default: true
     *
     * Catatan:
     * - Hanya lokal yang telah ditentukan yang ditunggu, sehingga halaman hanya
     *   mengunduh bahasa yang ditampilkannya.
     */
    dictionariesPreload: true,

    /**
     * Format output untuk file kamus yang dihasilkan.
     * Default: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * Menunjukkan apakah build harus memeriksa tipe TypeScript.
     * Default: false
     */
    checkTypes: false,
  },

  /**
   * Konfigurasi Logger.
   */
  log: {
    /**
     * Tingkat logging.
     * - "default": Logging standar.
     * - "verbose": Logging debug mendetail.
     * - "disabled": Tanpa logging.
     * Default: "default"
     */
    mode: "default",

    /**
     * Prefiks untuk semua pesan log.
     * Default: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * Konfigurasi sistem (Kasus penggunaan tingkat lanjut)
   */
  system: {
    /**
     * Direktori untuk menyimpan kamus lokalisasi.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * Direktori untuk augmentasi modul.
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * Direktori untuk menyimpan kamus yang tidak digabungkan.
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * Direktori untuk menyimpan tipe kamus.
     */
    typesDir: ".intlayer/types",

    /**
     * Direktori tempat file aplikasi utama disimpan.
     */
    mainDir: ".intlayer/main",

    /**
     * Direktori tempat file konfigurasi disimpan.
     */
    configDir: ".intlayer/config",

    /**
     * Direktori tempat file cache disimpan.
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * Konfigurasi kompiler (Kasus penggunaan tingkat lanjut)
   */
  compiler: {
    /**
     * Menunjukkan apakah kompiler harus diaktifkan.
     *
     * - false: Nonaktifkan kompiler.
     * - true: Aktifkan kompiler.
     * - "build-only": Lewati kompiler selama pengembangan dan mempercepat waktu mulai.
     *
     * Default: false
     */
    enabled: true,

    /**
     * Mendefinisikan path file output. Menggantikan `outputDir`.
     *
     * - Path `./` diselesaikan relatif terhadap direktori komponen.
     * - Path `/` diselesaikan relatif terhadap root proyek (`baseDir`).
     *
     * - Menyertakan variabel `{{locale}}` dalam path akan memicu pembuatan kamus terpisah per locale.
     *
     * Contoh:
     * ```ts
     * {
     *   // Buat file .content.ts Multibahasa di dekat komponen
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Setara menggunakan template string
     * }
     * ```
     *
     * ```ts
     * {
     *   // Buat JSON per-locale terpusat di root proyek
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Setara menggunakan template string
     * }
     * ```
     *
     * Daftar variabel:
     *   - `fileName`: Nama file.
     *   - `key`: Kunci konten.
     *   - `locale`: Locale konten.
     *   - `extension`: Ekstensi file.
     *   - `componentFileName`: Nama file komponen.
     *   - `componentExtension`: Ekstensi file komponen.
     *   - `format`: Format kamus.
     *   - `componentFormat`: Format kamus komponen.
     *   - `componentDirPath`: Path direktori komponen.
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * Menunjukkan apakah komponen harus disimpan setelah diubah.
     * Dengan begitu, kompiler dapat dijalankan hanya sekali untuk mengubah aplikasi, dan kemudian dapat dihapus.
     */
    saveComponents: false,

    /**
     * Masukkan hanya konten ke dalam file yang dihasilkan. Berguna untuk output i18next per-locale atau ICU MessageFormat JSON.
     */
    noMetadata: false,

    /**
     * Prefix kunci kamus
     */
    dictionaryKeyPrefix: "", // Menambahkan prefix opsional untuk kunci kamus yang diekstrak
  },

  /**
   * Skema kustom untuk memvalidasi isi kamus.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * Konfigurasi kamus.
   */
  dictionary: {
    /**
     * Mengontrol cara kamus diimpor.
     * - "static": Diimpor secara statis pada waktu build.
     * - "dynamic": Diimpor secara dinamis menggunakan Suspense.
     * - "fetch": Diambil secara dinamis melalui live sync API.
     */
    importMode: "static",

    /**
     * Format pesan default untuk semua kamus dalam proyek.
     * - 'intlayer': Format intlayer asli (default).
     * - 'icu': Format pesan ICU.
     * - 'i18next': Format i18next.
     * - 'vue-i18n': Format Vue I18n.
     * - 'po': Format GNU Gettext PO.
     */
    format: "icu",
  },

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

export default config;

routing: {
  mode: "prefix-no-default", // Strategi fallback
  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", // Cadangan untuk path yang tidak ditulis ulang
    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,
  },
};