Intlayer Compiler | Zautomatyzowane wydobywanie treści dla i18n

Czym jest Intlayer Compiler?

Intlayer Compiler to potężne narzędzie zaprojektowane w celu automatyzacji procesu internacjonalizacji (i18n) w Twoich aplikacjach. Przeszukuje Twój kod źródłowy (JSX, TSX, Vue, Svelte) w poszukiwaniu deklaracji treści, wydobywa je i automatycznie generuje niezbędne pliki słowników. Pozwala to na utrzymanie treści współlokalnie z komponentami, podczas gdy Intlayer zajmuje się zarządzaniem i synchronizacją Twoich słowników.

Dlaczego warto używać Intlayer Compiler?

• Automation: Eliminates manual copy-pasting of content into dictionaries.

• Speed: Zoptymalizowana ekstrakcja treści zapewniająca szybki proces budowania.

• Developer Experience: Trzymaj deklaracje zawartości tam, gdzie są używane, poprawiając łatwość utrzymania.

• Automatyzacja: Eliminuje ręczne kopiowanie i wklejanie treści do słowników.
• Szybkość: Optymalizowane wydobywanie treści zapewnia szybki proces budowania.
• Doświadczenie programisty: Zachowaj deklaracje treści dokładnie tam, gdzie są używane, co poprawia utrzymanie kodu.
• Aktualizacje na żywo: Obsługuje Hot Module Replacement (HMR) dla natychmiastowej informacji zwrotnej podczas budowania (build time) (build time) aplikacji.

Zobacz wpis na blogu Compiler vs. Declarative i18n dla głębszego porównania.

Dlaczego nie używać Intlayer Compiler?

Chociaż kompilator oferuje doskonałe doświadczenie "działa od razu", wprowadza również pewne kompromisy, o których powinieneś wiedzieć:

• Niejednoznaczność heurystyczna: Kompilator musi zgadywać, co jest treścią skierowaną do użytkownika, a co logiką aplikacji (np. className="active", kody statusu, ID produktów). W złożonych bazach kodu może to prowadzić do fałszywych pozytywów lub pominiętych ciągów znaków, które wymagają ręcznych adnotacji i wyjątków.

• Tylko statyczna ekstrakcja: Ekstrakcja oparta na kompilatorze opiera się na analizie statycznej. Ciągi znaków, które istnieją tylko w czasie wykonywania (kody błędów API, pola CMS itp.), nie mogą być odkryte ani przetłumaczone przez sam kompilator, więc nadal potrzebujesz uzupełniającej strategii i18n czasu wykonywania.

• Ekstrakcja tylko statyczna: Ekstrakcja oparta na kompilatorze polega na analizie statycznej. Ciągi znaków, które istnieją tylko w czasie wykonywania (kody błędów API, pola CMS itp.), nie mogą być odkryte ani przetłumaczone przez sam kompilator, dlatego nadal potrzebujesz dodatkowej strategii i18n w czasie wykonywania.

Aby uzyskać głębsze porównanie architektoniczne, zobacz wpis na blogu Compiler vs. Declarative i18n.

Jako alternatywę, aby zautomatyzować proces i18n przy zachowaniu pełnej kontroli nad treścią, Intlayer zapewnia również polecenie auto-ekstrakcji intlayer extract (zobacz dokumentację CLI) lub polecenie Intlayer: extract content to Dictionary z rozszerzenia Intlayer VS Code (zobacz dokumentację rozszerzenia VS Code).

Użycie

Najszybszym sposobem na podłączenie compilera jest interaktywna konfiguracja: uruchom npx intlayer init --interactive i wybierz Compiler. Na Vite nie ma nic do konfiguracji — compiler jest podłączony bezpośrednio przez główny plugin intlayer() (aktywuje się automatycznie, gdy compiler.enabled jest ustawiony i ścieżka compiler.output jest skonfigurowana). Na Next.js polecenie generuje plik babel.config.js pokazany poniżej. Nieinteraktywne intlayer init pozostawia konfigurację compilera bez zmian.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Dla Vue
npm install @intlayer/vue-compiler

# Dla Svelte
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // Wyodrębnij zawartość z komponentów do słowników
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // Optymalizuj importy, zastępując useIntlayer bezpośrednimi importami słowników
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Własna konfiguracja

Aby dostosować zachowanie kompilatora, możesz zaktualizować plik intlayer.config.ts w katalogu głównym swojego projektu.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * Wskazuje, czy kompilator powinien być włączony.
     * Ustaw na 'build-only', aby pominąć kompilator podczas programowania i przyspieszyć czas uruchamiania.
     */
    enabled: true,

    /**
     * Definiuje ścieżkę plików wyjściowych. Zastępuje `outputDir`.
     *
     * - Ścieżki zaczynające się od `./` są rozwiązywane względem katalogu komponentu.
     * - Ścieżki zaczynające się od `/` są rozwiązywane względem katalogu głównego projektu (`baseDir`).
     *
     * - Uwzględnienie zmiennej `{{locale}}` w ścieżce umożliwi generowanie słowników oddzielonych według języka.
     *
     * Przykłady:
     * ```ts
     * {
     *   // Utwórz wielojęzyczne pliki .content.ts obok komponentu
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Równoważne użycie szablonu ciągu znaków
     * }
     * ```
     *
     * ```ts
     * {
     *   // Utwórz scentralizowane pliki JSON według języka w katalogu głównym projektu
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Równoważne użycie szablonu ciągu znaków
     * }
     * ```
     *
     * Lista zmiennych:
     *   - `fileName`: Nazwa pliku.
     *   - `key`: Klucz zawartości.
     *   - `locale`: Język zawartoś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: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Wskazuje, czy komponenty powinny być zapisywane po transformacji.
     * W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.
     */
    saveComponents: false,

    /**
     * Wstaw tylko zawartość do wygenerowanego pliku. Przydatne dla wyjścia JSON i18next lub ICU MessageFormat na język.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * Prefiks klucza słownika
     */
    dictionaryKeyPrefix: "", // Dodaj opcjonalny prefiks dla wyekstrahowanych kluczy słownika
  },
};

Odniesienie do konfiguracji kompilatora

Następujące właściwości można skonfigurować w bloku compiler pliku intlayer.config.ts:

• enabled:

  • Typ: boolean | 'build-only'
  • Domyślny: true
  • Opis: Wskazuje, czy kompilator powinien być włączony.

• dictionaryKeyPrefix:

  • Typ: string
  • Domyślny: ''
  • Opis: Prefiks dla wyekstrahowanych kluczy słownika.

• transformPattern:

  • Typ: string | string[]
  • Domyślny: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Opis: (Zdeprecjonowane: użyj build.traversePattern zamiast tego) Wzorce do przeszukiwania kodu w celu optymalizacji.

• excludePattern:

  • Typ: string | string[]
  • Domyślny: ['**/node_modules/**']
  • Opis: (Zdeprecjonowane: użyj build.traversePattern zamiast tego) Wzorce do wykluczenia z optymalizacji.

• output:

  • Typ: FilePathPattern
  • Domyślny: ({ key }) => 'compiler/${key}.content.json'
  • Opis: Definiuje ścieżkę plików wyjściowych. Zastępuje outputDir. Obsługuje zmienne dynamiczne, takie jak {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Można ustawić jako ciąg znaków w formacie 'my/{{var}}/path' lub jako funkcję.
  • Uwaga: Ścieżki ./**/* są rozwiązywane względem komponentu. Ścieżki /**/* są rozwiązywane względem baseDir Intlayer.
  • Uwaga: Jeśli język jest zdefiniowany w ścieżce, słowniki będą generowane na język.
  • Przykład: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Typ: boolean
  • Domyślny: false
  • Opis: Wskazuje, czy metadane powinny być zapisywane w pliku. Jeśli true, kompilator nie będzie zapisywał metadanych słowników (klucza, otoczki zawartości). Przydatne dla wyjść JSON i18next lub ICU MessageFormat na lokalizację.
  • Uwaga: Przydatne w przypadku korzystania z wtyczki loadJSON.
  • Przykład: Jeśli true: json { "key": "value" } Jeśli false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Typ: boolean
  • Domyślny: false
  • Opis: Wskazuje, czy komponenty powinny być zapisywane po transformacji.

Uzupełnij brakujące tłumaczenia

Intlayer udostępnia narzędzie CLI, które pomaga uzupełnić brakujące tłumaczenia. Możesz użyć polecenia intlayer, aby przetestować i uzupełnić brakujące tłumaczenia w swoim kodzie.

npx intlayer test         # Sprawdź, czy brakuje tłumaczeń

npx intlayer fill         # Uzupełnij brakujące tłumaczenia

Ekstrakcja

Intlayer udostępnia narzędzie CLI do wyodrębniania treści z Twojego kodu. Możesz użyć polecenia intlayer extract, aby wyodrębnić treść ze swojego kodu.

npx intlayer extract

Więcej szczegółów znajdziesz w dokumentacji CLI