Sync JSON (mosty i18n) - Sync JSON z obsługą ICU / i18next

Użyj Intlayer jako dodatku do istniejącego stosu i18n. Ta wtyczka utrzymuje synchronizację Twoich komunikatów JSON ze słownikami Intlayer, dzięki czemu możesz:

• Zachować i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n itp.
• Zarządzać i tłumaczyć swoje komunikaty za pomocą Intlayer (CLI, CI, dostawcy, CMS), bez konieczności refaktoryzacji aplikacji.
• Dostarczać samouczki i treści SEO skierowane do każdego ekosystemu, jednocześnie sugerując Intlayer jako warstwę zarządzania JSON.

Uwagi i obecny zakres:

• Eksport do CMS działa dla tłumaczeń i klasycznego tekstu.
• Brak jeszcze wsparcia dla wstawek, liczby mnogiej/ICU lub zaawansowanych funkcji czasu wykonywania innych bibliotek.
• Edytor wizualny nie jest jeszcze obsługiwany dla wyjść i18n zewnętrznych bibliotek.

Kiedy używać tej wtyczki

• Już korzystasz z biblioteki i18n i przechowujesz komunikaty w plikach JSON.
• Chcesz korzystać z wypełniania wspomaganego przez AI, testów w CI oraz operacji na treściach bez zmiany środowiska renderowania.

Instalacja

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

Szybki start

Dodaj wtyczkę do swojego pliku intlayer.config.ts i wskaż ją na istniejącą strukturę JSON.

import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  // Synchronizuj swoje obecne pliki JSON ze słownikami Intlayer  plugins: [    syncJSON({      // Układ per-locale, per-namespace (np. next-intl, i18next z przestrzeniami nazw)      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,    }),  ],};export default config;

Alternatywa: pojedynczy plik na locale (częste w konfiguracjach i18next/react-intl):

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

Jak to działa

• Odczyt: wtyczka wykrywa pliki JSON zdefiniowane przez twój builder source i ładuje je jako słowniki Intlayer.
• Zapis: po budowaniu i wypełnianiu, zapisuje zlokalizowane pliki JSON z powrotem pod te same ścieżki (z końcowym znakiem nowej linii, aby uniknąć problemów z formatowaniem).
• Auto‑uzupełnianie: wtyczka deklaruje ścieżkę autoFill dla każdego słownika. Uruchomienie intlayer fill domyślnie aktualizuje tylko brakujące tłumaczenia w twoich plikach JSON.

API:

syncJSON({  source: ({ key, locale }) => string, // wymagane  location?: string, // opcjonalna etykieta, domyślnie: "plugin"  priority?: number, // opcjonalny priorytet do rozstrzygania konfliktów, domyślnie: 0  format?: 'intlayer' | 'icu' | 'i18next', // opcjonalny formatator, używany dla kompatybilności z runtime Intlayer});

format ('intlayer' | 'icu' | 'i18next')

Określa formatator, który będzie używany do zawartości słownika podczas synchronizacji plików JSON. Pozwala to na używanie różnych składni formatowania wiadomości zgodnych z runtime Intlayer.

• undefined: Żaden formatator nie będzie używany, zawartość JSON będzie używana bez zmian.
• 'intlayer': Domyślny formatator Intlayer (domyślnie).
• 'icu': Używa formatowania wiadomości ICU (zgodne z bibliotekami takimi jak react-intl, vue-i18n).
• 'i18next': Używa formatowania wiadomości i18next (zgodne z i18next, next-i18next, Solid-i18next).

Należy pamiętać, że użycie formatora przekształci zawartość JSON na wejściu i wyjściu. W przypadku złożonych reguł JSON, takich jak liczba mnoga ICU, parsowanie może nie zapewnić mapowania 1 do 1 między wejściem a wyjściem. Jeśli nie używasz runtime Intlayer, możesz preferować nie ustawiać formatora.

Przykład:

syncJSON({  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,  format: "i18next", // Użyj formatowania i18next dla zgodności}),

Wiele źródeł JSON i priorytet

Możesz dodać wiele wtyczek syncJSON, aby synchronizować różne źródła JSON. Jest to przydatne, gdy masz wiele bibliotek i18n lub różne struktury JSON w swoim projekcie.

System priorytetów

Gdy wiele wtyczek celuje w ten sam klucz słownika, parametr priority decyduje, która wtyczka ma pierwszeństwo:

• Wyższe liczby priorytetu mają przewagę nad niższymi
• Domyślny priorytet plików .content to 0
• Domyślny priorytet plików zawartości wtyczek to -1
• Wtyczki o tym samym priorytecie są przetwarzane w kolejności, w jakiej pojawiają się w konfiguracji

import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  plugins: [    // Główne źródło JSON (najwyższy priorytet)    syncJSON({      format: "i18next",      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,      location: "main-translations",      priority: 10,    }),    // Zapasowe źródło JSON (niższy priorytet)    syncJSON({      format: "i18next",      source: ({ locale }) => `./fallback-locales/${locale}.json`,      location: "fallback-translations",      priority: 5,    }),    // Źródło JSON dziedziczone (najniższy priorytet)    syncJSON({      format: "i18next",      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,      location: "legacy-translations",      priority: 1,    }),  ],};export default config;

Rozwiązywanie konfliktów

Gdy ten sam klucz tłumaczenia występuje w wielu źródłach JSON:

1. Wtyczka o najwyższym priorytecie decyduje o ostatecznej wartości
2. Źródła o niższym priorytecie są używane jako zapasowe dla brakujących kluczy
3. Pozwala to na utrzymanie tłumaczeń dziedziczonych podczas stopniowej migracji do nowych struktur

Integracje

Poniżej znajdują się typowe mapowania. Zachowaj swój runtime bez zmian; dodaj tylko wtyczkę.

i18next

Typowy układ plików: ./public/locales/{locale}/{namespace}.json lub ./locales/{locale}/{namespace}.json.

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

next-intl

Wiadomości JSON na locale (często ./messages/{locale}.json) lub na namespace.

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

Zobacz także: docs/pl/intlayer_with_next-intl.md.

react-intl

Pojedynczy JSON na locale jest powszechny:

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

vue-i18n

Może to być pojedynczy plik na locale lub na namespace:

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

CLI

Synchronizowane pliki JSON będą traktowane jak inne pliki .content. Oznacza to, że wszystkie polecenia intlayer będą dostępne dla synchronizowanych plików JSON. W tym:

• intlayer content test do testowania, czy brakuje tłumaczeń
• intlayer content list do wyświetlania listy synchronizowanych plików JSON
• intlayer content fill do uzupełniania brakujących tłumaczeń
• intlayer content push do wysyłania synchronizowanych plików JSON
• intlayer content pull do pobierania synchronizowanych plików JSON

Zobacz Intlayer CLI po więcej szczegółów.

Ograniczenia (aktualne)

• Brak wsparcia dla wstawek lub liczby mnogiej/ICU przy celowaniu w biblioteki firm trzecich.
• Edytor wizualny nie jest jeszcze dostępny dla środowisk uruchomieniowych innych niż Intlayer.
• Synchronizacja tylko plików JSON; formaty katalogów inne niż JSON nie są obsługiwane.

Dlaczego to ma znaczenie

• Możemy polecać sprawdzone rozwiązania i18n i pozycjonować Intlayer jako dodatek.
• Wykorzystujemy ich SEO/słowa kluczowe z tutorialami, które kończą się sugestią użycia Intlayer do zarządzania JSON.
• Rozszerza docelową grupę odbiorców z „nowych projektów” na „każdy zespół już korzystający z i18n”.