Tłumaczenia plików deklaracji wypełniania zawartości

Pliki deklaracji autouzupełniania w Twoim CI to sposób na przyspieszenie procesu tworzenia oprogramowania.

Zrozumienie zachowania

Polecenie fill zawiera dwa tryby:

• Complete: Automatycznie wypełnia całą brakującą treść dla każdej lokalizacji i edytuje bieżący plik lub inny plik, jeśli jest określony. To znaczy, tryb complete pominiesz tłumaczenie istniejącej treści, jeśli jest już przetłumaczona.
• Review: Automatycznie wypełnia całą treść dla każdej lokalizacji i generuje dla określonego pliku lub innego pliku, jeśli jest określony.

Polecenie fill będzie przetwarzać wszystkie pliki deklaracji treści lokalizacji. To znaczy, nie będzie przetwarzać zdalnej treści z CMS. CMS zawiera własne zarządzanie tłumaczeniami. Jeśli używasz wtyczek takich jak @intlayer/sync-json-plugin, Intlayer przekształci pliki JSON w pliki deklaracji treści lokalizacji. To znaczy, będą przetwarzane przez polecenie fill.

Nowo wygenerowane pliki zawierają instrukcję filled jako metadane słownika. Instrukcja ta będzie używana przez Intlayer do określenia, czy plik został automatycznie wypełniony, czy nie, i pominie ten plik z ponownego tłumaczenia, jeśli jest obecny.

Intlayer będzie również uwzględniać następującą instrukcję do automatycznego wypełniania:

• Z twojego pliku .content.{ts|js|json} → instrukcja fill
• Z pliku konfiguracyjnego .intlayer.config.ts → instrukcja dictionary.fill
• Będzie domyślnie ustawiona na true w przeciwnym razie

W przypadku plików deklaracji treści dla poszczególnych lokalizacji instrukcja true zostanie zastąpiona przez ./{{fileName}}.fill.content.json. Dzieje się tak, ponieważ plik deklaracji treści dla poszczególnych lokalizacji nie może otrzymać dodatkowej zlokalizowanej treści. Dlatego wygeneruje nowy plik, aby nie nadpisać istniejącego pliku.

Domyślne zachowanie

Domyślnie fill jest ustawione globalnie na true, co oznacza, że Intlayer automatycznie wypełni wszystkie pliki zawartości i edytuje sam plik. To zachowanie można dostosować na kilka sposobów:

Globalne opcje konfiguracji

1. fill: true (domyślnie) - Automatyczne wypełnianie wszystkich lokalizacji i edycja bieżącego pliku
2. fill: false - Wyłączenie autouzupełniania dla tego pliku zawartości
3. fill: "path/to/file" - Utworzenie/aktualizacja określonego pliku bez edycji bieżącego
4. fill: { [key in Locales]?: string } - Utworzenie/aktualizacja określonego pliku dla każdej lokalizacji

Zmiany zachowania w wersji v7

W wersji 7 zachowanie polecenia fill zostało zaktualizowane:

• fill: true - Nadpisuje bieżący plik wypełnioną zawartością dla wszystkich lokalizacji
• fill: "path/to/file" - Wypełnia określony plik bez modyfikowania bieżącego pliku
• fill: false - Całkowicie wyłącza autouzupełnianie

Podczas używania opcji ścieżki do zapisu do innego pliku, mechanizm wypełniania działa na zasadzie relacji master-slave między plikami deklaracji zawartości. Główny (master) plik służy jako źródło prawdy, a gdy zostanie zaktualizowany, Intlayer automatycznie zastosuje te zmiany do pochodnych (wypełnionych) plików deklaracji określonych przez ścieżkę.

Dostosowanie dla poszczególnych lokalizacji

Możesz również dostosować zachowanie dla każdej lokalizacji, używając obiektu:

const config: IntlayerConfig = {  content: {    internationalization: {      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],      defaultLocale: Locales.ENGLISH,      requiredLocales: [Locales.ENGLISH], // Zalecane, aby uniknąć błędu Property 'pl' is missing in type '{ en: string; xxx }' w funkcji t    },  },  dictionary: {    fill: {      en: true, // Wypełnij i edytuj bieżący plik dla języka angielskiego      fr: "./translations/fr.json", // Utwórz osobny plik dla języka francuskiego      es: false, // Wyłącz wypełnianie dla języka hiszpańskiego    },  },};

To pozwala na różne zachowania wypełniania dla różnych lokalizacji w ramach tego samego projektu.

import { Locales, type Dictionary } from "intlayer";const exampleContent = {  key: "example",  locale: Locales.ENGLISH,  fill: "./example.content.json",  content: {    contentExample: "To jest przykład zawartości",  },} satisfies Dictionary;export default exampleContent;

Oto plik deklaracji zawartości dla poszczególnych lokalizacji wykorzystujący instrukcję fill.

Następnie, gdy uruchomisz następujące polecenie:

npx intlayer fill --file 'src/components/example/example.content.ts'

Intlayer automatycznie wygeneruje pochodny plik deklaracji w src/components/example/example.content.json, wypełniając wszystkie lokalizacje, które nie zostały jeszcze zadeklarowane w głównym pliku.

{  "key": "example",  "content": {    "contentExample": {      "nodeType": "translation",      "translation": {        "fr": "Ceci est un exemple de contenu",        "es": "Este es un ejemplo de contenido",      },    },  },}

Następnie oba pliki deklaracji zostaną scalone w jeden słownik, dostępny za pomocą standardowego hooka useIntlayer("example") (react) / composable (vue).

Konfiguracja globalna

Możesz skonfigurować globalną konfigurację automatycznego wypełniania w pliku intlayer.config.ts.

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],  },  dictionary: {    // Automatyczne generowanie brakujących tłumaczeń dla wszystkich słowników    fill: "./{{fileName}}Filled.content.ts",    //    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",    //    // fill: true, // automatyczne generowanie brakujących tłumaczeń dla wszystkich słowników, jak przy użyciu "./{{fileName}}.content.json"    //    // fill: {    //   en: "./{{fileName}}.en.content.json",    //   fr: "./{{fileName}}.fr.content.json",    //   es: "./{{fileName}}.es.content.json",    // },  },};export default config;

Możesz nadal precyzyjnie dostosować konfigurację dla poszczególnych słowników, używając pola fill w plikach z zawartością. Intlayer najpierw uwzględni konfigurację dla konkretnego słownika, a następnie, w razie potrzeby, przejdzie do konfiguracji globalnej.

Format pliku automatycznie wypełnianego

Zalecanym formatem dla automatycznie wypełnianych plików deklaracji jest JSON, co pomaga uniknąć ograniczeń formatowania. Jednak Intlayer obsługuje również formaty .ts, .js, .mjs, .cjs oraz inne.

const exampleContent = {  key: "example",  fill: "./example.filled.content.ts",  content: {    // Twoja zawartość  },};

To spowoduje wygenerowanie pliku pod ścieżką:

src/components/example/example.filled.content.ts

Generowanie plików .js, .ts i podobnych działa w następujący sposób:

• Jeśli plik już istnieje, Intlayer przeanalizuje go za pomocą AST (Abstract Syntax Tree), aby zlokalizować każde pole i wstawić brakujące tłumaczenia.
• Jeśli plik nie istnieje, Intlayer wygeneruje go, używając domyślnego szablonu pliku deklaracji zawartości.

Ścieżki bezwzględne

Pole fill obsługuje również ścieżki bezwzględne.

const exampleContent = {  key: "example",  fill: "/messages/example.content.json",  content: {    // Twoja zawartość  },};

To wygeneruje plik pod ścieżką:

/messages/example.content.json

Automatyczne generowanie plików deklaracji zawartości dla poszczególnych lokalizacji

Pole fill obsługuje również generowanie plików deklaracji zawartości dla poszczególnych lokalizacji.

const exampleContent = {  key: "example",  fill: {    fr: "./example.fr.content.json",    es: "./example.es.content.json",  },  content: {    // Twoja zawartość  },};

To wygeneruje dwa oddzielne pliki:

• src/components/example/example.fr.content.json
• src/components/example/example.es.content.json

W tym przypadku, jeśli obiekt nie zawiera wszystkich lokalizacji, Intlayer pomija generowanie pozostałych lokalizacji.

Filtrowanie automatycznego wypełniania dla konkretnej lokalizacji

Użycie obiektu w polu fill pozwala na zastosowanie filtrów i generowanie tylko plików dla określonych lokalizacji.

const exampleContent = {  key: "example",  fill: {    fr: "./example.fr.content.json",  },  content: {    // Twoja zawartość  },};

To wygeneruje tylko plik z tłumaczeniem na język francuski.

Zmienne ścieżek

Możesz używać zmiennych w ścieżce fill, aby dynamicznie rozwiązywać docelowe ścieżki dla generowanych plików.

Dostępne zmienne:

• {{locale}} – Kod lokalizacji (np. fr, es)
• {{fileName}} – Nazwa pliku (np. index)
• {{key}} – Klucz słownika (np. example)

const exampleContent = {  key: "example",  fill: "/messages/{{locale}}/{{key}}.content.json",  content: {    // Twoja zawartość  },};

To wygeneruje:

• /messages/fr/example.content.json
• /messages/es/example.content.json

const exampleContent = {  key: "example",  fill: "./{{fileName}}.content.json",  content: {    // Twoja zawartość  },};

To wygeneruje:

• ./index.content.json
• ./index.content.json