Sinkronisasi JSON (jembatan i18n)

Gunakan Intlayer sebagai tambahan pada tumpukan i18n Anda yang sudah ada. Plugin ini menjaga pesan JSON Anda tetap sinkron dengan kamus Intlayer sehingga Anda dapat:

• Mempertahankan i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n, dll.
• Mengelola dan menerjemahkan pesan Anda dengan Intlayer (CLI, CI, penyedia, CMS), tanpa perlu merombak aplikasi Anda.
• Mengirimkan tutorial dan konten SEO yang menargetkan setiap ekosistem, sambil menyarankan Intlayer sebagai lapisan pengelolaan JSON.

Catatan dan cakupan saat ini:

• Eksternalisasi ke CMS berfungsi untuk terjemahan dan teks klasik.
• Belum mendukung penyisipan, bentuk jamak/ICU, atau fitur runtime lanjutan dari pustaka lain.
• Editor visual belum didukung untuk output i18n pihak ketiga.

Kapan menggunakan plugin ini

• Anda sudah menggunakan perpustakaan i18n dan menyimpan pesan dalam file JSON.
• Anda menginginkan pengisian berbantuan AI, pengujian di CI, dan operasi konten tanpa mengubah runtime rendering Anda.

Instalasi

pnpm add -D @intlayer/sync-json-plugin# ataunpm i -D @intlayer/sync-json-plugin

Mulai cepat

Tambahkan plugin ke intlayer.config.ts Anda dan arahkan ke struktur JSON yang sudah ada.

import { defineConfig, Locales } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";export default defineConfig({  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  // Jaga file JSON Anda saat ini tetap sinkron dengan kamus Intlayer  plugins: [    syncJSON({      // Tata letak per-locale, per-namespace (misalnya, next-intl, i18next dengan namespaces)      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,    }),  ],});

Alternatif: satu file per locale (umum dengan pengaturan i18next/react-intl):

plugins: [  syncJSON({    source: ({ locale }) => `./locales/${locale}.json`,  }),];

Cara kerjanya

• Baca: plugin menemukan file JSON dari pembangun source Anda dan memuatnya sebagai kamus Intlayer.
• Tulis: setelah proses build dan pengisian, plugin menulis kembali JSON yang sudah dilokalkan ke jalur yang sama (dengan newline akhir untuk menghindari masalah format).
• Auto‑fill: plugin mendeklarasikan jalur autoFill untuk setiap kamus. Menjalankan intlayer fill secara default hanya memperbarui terjemahan yang hilang dalam file JSON Anda.

API:

syncJSON({  source: ({ key, locale }) => string, // wajib  location?: string, // label opsional, default: "plugin"  priority?: number, // prioritas opsional untuk resolusi konflik, default: 0});

Beberapa sumber JSON dan prioritas

Anda dapat menambahkan beberapa plugin syncJSON untuk menyinkronkan berbagai sumber JSON. Ini berguna ketika Anda memiliki beberapa pustaka i18n atau struktur JSON yang berbeda dalam proyek Anda.

Sistem prioritas

Ketika beberapa plugin menargetkan kunci kamus yang sama, parameter priority menentukan plugin mana yang diutamakan:

• Angka prioritas yang lebih tinggi menang atas yang lebih rendah
• Prioritas default untuk file .content adalah 0
• Prioritas default untuk file konten plugin adalah -1
• Plugin dengan prioritas yang sama diproses sesuai urutan kemunculannya dalam konfigurasi

import { defineConfig, Locales } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";export default defineConfig({  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  plugins: [    // Sumber JSON utama (prioritas tertinggi)    syncJSON({      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,      location: "main-translations",      priority: 10,    }),    // Sumber JSON cadangan (prioritas lebih rendah)    syncJSON({      source: ({ locale }) => `./fallback-locales/${locale}.json`,      location: "fallback-translations",      priority: 5,    }),    // Sumber JSON Legacy (prioritas terendah)    syncJSON({      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,      location: "legacy-translations",      priority: 1,    }),  ],});

Penyelesaian konflik

Ketika kunci terjemahan yang sama ada di beberapa sumber JSON:

1. Plugin dengan prioritas tertinggi menentukan nilai akhir
2. Sumber dengan prioritas lebih rendah digunakan sebagai cadangan untuk kunci yang hilang
3. Ini memungkinkan Anda mempertahankan terjemahan legacy sambil secara bertahap bermigrasi ke struktur baru

Integrasi

Berikut adalah pemetaan umum. Biarkan runtime Anda tetap tidak berubah; hanya tambahkan plugin.

i18next

Tata letak file tipikal: ./public/locales/{locale}/{namespace}.json atau ./locales/{locale}/{namespace}.json.

import { syncJSON } from "@intlayer/sync-json-plugin";export default {  plugins: [    syncJSON({      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,    }),  ],};

next-intl

Pesan JSON per-locale (sering ./messages/{locale}.json) atau per-namespace.

plugins: [  syncJSON({    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,  }),];

Lihat juga: docs/id/intlayer_with_next-intl.md.

react-intl

JSON tunggal per locale adalah umum:

plugins: [  syncJSON({    source: ({ locale }) => `./locales/${locale}.json`,  }),];

vue-i18n

Baik satu file per locale atau per-namespace:

plugins: [  syncJSON({    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,  }),];

CLI

File JSON yang disinkronkan akan dianggap sebagai file .content lainnya. Artinya, semua perintah intlayer akan tersedia untuk file JSON yang disinkronkan. Termasuk:

• intlayer content test untuk menguji apakah ada terjemahan yang hilang
• intlayer content list untuk mendaftar file JSON yang disinkronkan
• intlayer content fill untuk mengisi terjemahan yang hilang
• intlayer content push untuk mengirim file JSON yang disinkronkan
• intlayer content pull untuk menarik file JSON yang disinkronkan

Lihat Intlayer CLI untuk detail lebih lanjut.

Keterbatasan (saat ini)

• Tidak ada dukungan penyisipan atau bentuk jamak/ICU saat menargetkan pustaka pihak ketiga.
• Editor visual belum tersedia untuk runtime non-Intlayer.
• Sinkronisasi hanya untuk JSON; format katalog non-JSON tidak didukung.

Mengapa ini penting

• Kami dapat merekomendasikan solusi i18n yang sudah mapan dan memposisikan Intlayer sebagai tambahan.
• Kami memanfaatkan SEO/kata kunci mereka dengan tutorial yang berakhir dengan menyarankan Intlayer untuk mengelola JSON.
• Memperluas audiens yang dapat dijangkau dari “proyek baru” menjadi “tim mana pun yang sudah menggunakan i18n”.