@intlayer/docs 9.4.2 → 9.4.3

package/blog/pl/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Formatowanie dat i liczb według lokalizacji za pomocą Intl"
+description: Prawdopodobnie nie potrzebujesz zewnętrznej biblioteki do formatowania. Jak Intl obsługuje daty, liczby, waluty i listy per locale, koszt cache'owania oraz błąd strefy czasowej na produkcji.
+keywords:
+  - formatowanie daty per locale
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - format waluty locale
+  - format czasu względnego
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Formatowanie dat i liczb według lokalizacji za pomocą Intl
+
+Tłumaczenie tekstów to zaledwie widoczna połowa internacjonalizacji (i18n). Druga połowa, która regularnie generuje zgłoszenia błędów, to formatowanie: niemiecki użytkownik widzący `1,234.56` zamiast `1.234,56`, japoński użytkownik widzący `08/02/2026` i czytający to jako sierpień, lub data renderująca się inaczej na serwerze i w przeglądarce, powodująca błąd hydratacji w React.
+
+Żadna z tych rzeczy nie wymaga zewnętrznej biblioteki. API `Intl` jest wbudowane w każde współczesne środowisko wykonawcze.
+
+## Spis treści
+
+<TOC/>
+
+## Zacznij od usunięcia własnoręcznie napisanych helperów do dat
+
+Niemal każda baza kodu zawiera funkcję `formatDate` napisaną, zanim ktokolwiek pomyślał o lokalizacjach. Narzuca ona sztywną kolejność, separator i najczęściej angielskie nazwy miesięcy.
+
+```ts
+// Kod, który należy usunąć:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` zastępuje ją w pełni i działa prawidłowo dla każdego języka:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+To samo dotyczy liczb. `toFixed(2)` wszędzie daje `1234.56`, co w większości krajów Europy jest zapisem niepoprawnym.
+
+## Co obejmuje `Intl`
+
+| API                       | Zastosowanie                                                   |
+| :------------------------ | :------------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Daty i godziny z presetami `dateStyle` / `timeStyle`           |
+| `Intl.NumberFormat`       | Ułamki dziesiętne, waluty, procenty, jednostki, notacja zwarta |
+| `Intl.RelativeTimeFormat` | "3 dni temu", "za 2 godziny"                                   |
+| `Intl.ListFormat`         | "a, b i c" kontra "a, b, and c"                                |
+| `Intl.PluralRules`        | Ustalanie reguł liczby mnogiej dla wartości liczbowych         |
+| `Intl.Collator`           | Poprawne językowo sortowanie ciągów znaków                     |
+
+`Intl.Collator` to narzędzie, o którym programiści zapominają najczęściej. Wywołanie `array.sort()` na ciągach znaków używa kolejności punktów kodowych Unicode, przez co litery ze znakami diakrytycznymi trafiają na sam koniec za `z`, a szwedzkie `ö` ląduje w niewłaściwym miejscu. Sortując listy widoczne dla użytkowników, zawsze używaj collatora.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("pl").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Wybieraj gotowe presety zamiast opcji składanych ręcznie
+
+`dateStyle` i `timeStyle` pozwalają lokalizacji samodzielnie decydować o logicznym układzie i separatorach. Ręczne konfigurowanie `year`, `month` i `day` daje kontrolę, której zazwyczaj nie chcesz, ponieważ prawidłowy układ zależy od regionu i nadpisujesz dane CLDR własnymi, często błędnymi założeniami.
+
+```ts
+// Układ określa dana lokalizacja:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Wymuszenie własnego układu, błędnego w innych krajach:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Używaj jawnych komponentów tylko wtedy, gdy projekt graficzny bezwzględnie wymaga stałej szerokości, np. w wąskiej kolumnie tabeli.
+
+## Tworzenie formaterów jest kosztowne
+
+Oto szczegół wydajnościowy o fundamentalnym znaczeniu. Inicjalizacja `Intl.NumberFormat` ładuje obszerne dane lokalizacyjne i jest znacznie droższa niż samo wywołanie `.format()`. Wykonywanie tego w pętli renderującej po tysiącu wierszy powoduje wyraźny spadek płynności.
+
+```ts
+// Ponowne tworzenie formatera dla każdego wiersza (wolne):
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Utworzenie raz i wielokrotne użycie (szybkie):
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` i `toLocaleString()` kryją w sobie ten sam problem: każde wywołanie tworzy nową instancję. Sprawdzają się dla pojedynczej wartości, ale są nieodpowiednie dla list.
+
+Cache'uj instancje w oparciu o połączenie lokalizacji i opcji:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Błąd strefy czasowej, który pojawia się wyłącznie na produkcji
+
+Ten błąd potrafi kosztować całe popołudnia. Serwer renderuje datę w SSR, przeglądarka przeprowadza hydratację w kliencie, a React zgłasza błąd hydration mismatch, ponieważ oba środowiska wygenerowały różny tekst.
+
+Przyczyna: `Intl.DateTimeFormat` używa lokalnej strefy czasowej systemu operacyjnego, jeśli nie wskażesz jej wprost. Serwer produkcyjny działa w UTC, podczas gdy komputer lokalny programisty w innej strefie. Błąd jest niewidoczny lokalnie i ujawnia się dopiero na produkcji.
+
+```ts
+// Serwer w UTC i przeglądarka w UTC+1 generują różne teksty. Błąd hydratacji:
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Oba środowiska generują w pełni spójny tekst:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Trzy sprawdzone podejścia:
+
+- **Ustalenie strefy czasowej** na serwerze i jawne jej przekazywanie. Stabilne i deterministyczne, ale każdy widzi czas UTC.
+- **Renderowanie wyłącznie po stronie klienta**, ze stabilnym placeholderem w fazie SSR. Dokładne dla użytkownika, z drobnym przeskokiem wizualnym.
+- **Zapisanie strefy czasowej użytkownika** i przekazywanie jej do obu środowisk. Najlepszy rezultat, wymagający nieco więcej konfiguracji.
+
+Niezależnie od wyboru, zawsze jawnie podawaj `timeZone` dla każdej daty renderowanej zarówno po stronie serwera, jak i klienta. Data bez zdefiniowanej strefy czasowej to data o dwóch różnych wartościach.
+
+## Waluta potrzebuje kodu waluty, a nie lokalizacji
+
+Lokalizacja i waluta to niezależne pojęcia. `fr-FR` nie oznacza automatycznie euro: francuski klient może przeglądać fakturę rozliczaną w dolarach amerykańskich.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+Lokalizacja zarządza separatorami, grupowaniem cyfr i pozycją symbolu. Sama waluta pochodzi z danych biznesowych. Wnioskowanie jednego z drugiego prowadzi do poważnych błędów księgowych.
+
+Zwróć także uwagę na `currencyDisplay`. W interfejsach, w których występuje kilka walut dzielących znak dolara ($), opcja `"code"` eliminuje nieporozumienia pomiędzy dolarami amerykańskimi, kanadyjskimi i australijskimi.
+
+## Czas względny jest bardziej czytelny niż sztywny timestamp
+
+W przypadku niedawnych zdarzeń "2 godziny temu" jest znacznie bardziej naturalne niż pełna data, a `Intl.RelativeTimeFormat` lokalizuje ten zapis automatycznie.
+
+```ts
+new Intl.RelativeTimeFormat("pl", { numeric: "auto" }).format(-1, "day");
+// "wczoraj"
+```
+
+`numeric: "auto"` odpowiada za uzyskanie słowa "wczoraj" zamiast "1 dzień temu".
+
+## Co dodaje Intlayer
+
+Intlayer opakowuje te mechanizmy w funkcje pomocnicze z wbudowanym cache'em, uwalniając Cię od ręcznego zarządzania strukturą Map, i automatycznie stosuje aktywną lokalizację bez konieczności przekazywania jej przy każdym wywołaniu.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1 234,5"
+currency(1234.5, { currency: "EUR" }); // "1 234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 godziny temu"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 kilometrów"
+compact(1200); // "1,2 tys."
+list(["jabłko", "banan", "pomarańcza"]); // "jabłko, banan i pomarańcza"
+```
+
+Funkcja `date()` obsługuje także presety (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`). Dla Reacta i Vue dostępne są hooki i composables, które automatycznie pobierają język z kontekstu.
+
+Jest to wygodna warstwa pamięci podręcznej i obsługi domyślnego języka nad standardowym API platformy. Sam sposób formatowania w pełni opiera się na `Intl`. Pełne sygnatury znajdziesz w [dokumentacji formaterów](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/formatters.md).
+
+## Częste błędy
+
+- **`toLocaleDateString()` bez podania lokalizacji.** Pobiera język środowiska uruchomieniowego, zależny od konfiguracji kontenera serwera.
+- **Formatowanie w pętli bez cache'owania.** Tworzenie formatera pochłania większość czasu CPU.
+- **Brak parametru `timeZone` przy datach izomorficznych.** Prowadzi do błędów hydratacji niewidocznych lokalnie.
+- **Wnioskowanie waluty z języka.** `fr-FR` nie gwarantuje rozliczeń w euro.
+- **Używanie zwykłego `sort()` dla wyświetlanych tekstów.** Zawsze stosuj `Intl.Collator`.
+- **Wpisywanie nazw miesięcy i dni na sztywno.** Są już kompleksowo opisane w repozytorium CLDR dla każdego języka.
+- **Pozostawianie `numeric: "always"` w czasie względnym.** Zwraca "1 dzień temu" tam, gdzie istnieje słowo wczoraj.
+
+## Warto przeczytać
+
+- [Formatery i narzędzia lokalizacyjne: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/formatters.md)
+- [Dokumentacja konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Raporty wydajnościowe frameworków](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md)
+- [Adapter kompatybilności react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/react-intl.md)
+- [Format wiadomości ICU: liczba mnoga, instrukcje warunkowe i szablony liczb](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/icu_message_format.md)
+- [Jak testować tłumaczenia z uwzględnieniem formaterów i reguł liczby mnogiej](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/i18n_testing_strategies.md)
+- [Co w rzeczywistości obejmuje internacjonalizacja](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/what_is_internationalization.md)

package/blog/pl/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Jak wykrywać brakujące tłumaczenia, zanim zrobią to użytkownicy"
+description: Brakujące tłumaczenia zawodzą po cichu. Dlaczego mechanizm fallback je ukrywa, jakie cztery warstwy wykrywania naprawdę działają i jak zatrzymać build na nieprzetłumaczonym kluczu.
+keywords:
+  - znajdź brakujące tłumaczenia
+  - brakujące klucze tłumaczeń
+  - audyt i18n
+  - nieprzetłumaczone ciągi znaków
+  - pokrycie tłumaczeń
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Jak wykrywać brakujące tłumaczenia, zanim zrobią to użytkownicy
+
+Brakujące tłumaczenie prawie nigdy nie rzuca wyjątku. W zależności od konfiguracji wyświetla japońskiemu użytkownikowi tekst po angielsku lub drukuje `checkout.summary.total` wprost na stronie produkcyjnej. Obydwa przypadki trafiają na produkcję, przechodzą code review i zostają zauważone przez klienta, a nie przez Ciebie.
+
+## Spis treści
+
+<TOC/>
+
+## Dotyczy to każdej biblioteki, której używasz
+
+Nic z tego, co tu opisano, nie jest ograniczone do jednego konkretnego stosu technologicznego. Poniższe warstwy detekcji działają identycznie w i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate czy Lingui, ponieważ wszystkie rozwiązują klucze w ten sam sposób i zawodzą według tego samego schematu.
+
+Narzędzia również są przenośne. Jeśli Twoje teksty znajdują się w katalogach JSON, [wtyczka Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-json.md) podłącza Intlayer do tych plików, dając Ci dostęp do poleceń audytu, wypełniania i testowania bez przenoszenia treści i bez zmiany choćby jednego importu:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // lub "icu" dla next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Jeśli zależy Ci również na zachowaniu dotychczasowego runtime API, [adaptery kompatybilności](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md) tworzą aliasy dla `useTranslation`, `$t` i pokrewnych na poziomie bundlera. W każdym przypadku traktuj poniższe komendy jako praktyczną realizację koncepcji, a nie sztywny wymóg.
+
+## Dlaczego braki są niewidoczne
+
+Każda biblioteka i18n rozwiązuje klucz według tego samego łańcucha: sprawdź aktywny język, sięgnij po język domyślny (fallback), a jeśli to zawiedzie, zwróć sam klucz. To właśnie ten ostatni krok stanowi sedno problemu. Nie ma błędu, nie ma ostrzeżenia na produkcji i żaden test nie zgłasza awarii, ponieważ żaden element potoku nie traktuje brakującego klucza jako anomalii.
+
+Fallback tylko pogarsza sprawę zamiast ją naprawiać. Strona renderująca się po cichu w języku angielskim wygląda całkowicie poprawnie dla anglojęzycznego programisty i dla każdego zautomatyzowanego testu. Błąd jest widoczny wyłącznie dla osoby, która nie rozumie wyświetlonego tekstu.
+
+Pytanie nie brzmi zatem "jak obsługiwać brakujące tłumaczenia w runtime". Brzmi ono: "jak uniemożliwić zmergowanie brakującego tłumaczenia".
+
+## Cztery warstwy, w których możesz je wychwycić
+
+Każda warstwa wyłapuje to, czego inne nie potrafią dostrzec. Najlepiej wdrożyć więcej niż jedną.
+
+| Warstwa            | Co wykrywa                                       | Co pomija                                                |
+| :----------------- | :----------------------------------------------- | :------------------------------------------------------- |
+| Typy               | Klucze, które w ogóle nie istnieją               | Klucz istnieje, ale nie ma wartości w `ja`               |
+| Linter             | Teksty na sztywno, niewysłane do tłumaczenia     | Klucze brakujące w konkretnym katalogu                   |
+| Audyt              | Pokrycie językowe każdego zadeklarowanego klucza | Teksty, które nigdy nie zostały oznaczone do tłumaczenia |
+| Testy renderowania | Klucze, które się rozwiązują, ale źle renderują  | Wszystko, co nie zostało objęte testem                   |
+
+Najczęstszą luką w zespołach jest trzeci wiersz: programiści wiedzą, że ich klucze są poprawne pod kątem typów, ale nic nie sprawdza, czy wszystkie osiemnaście języków rzeczywiście posiada przypisaną wartość.
+
+## Warstwa 1: uczyń klucz typem, a nie ciągiem znaków
+
+`t("checkout.summry.total")` to literówka, która bez trudu się kompiluje. Jeśli Twoje klucze są zwykłymi ciągami znaków, każda zmiana nazwy niesie ryzyko na produkcji, a każde usunięcie pozostawia osierocone wpisy.
+
+Typowane klucze zamieniają to w błąd kompilacji. `react-i18next` wspiera to przez declaration merging, `next-intl` wnioskuje typy ze struktury wiadomości, Lingui generuje identyfikatory z tekstu źródłowego, a Intlayer tworzy ścisłe typy z plików deklaracji. Każde z tych rozwiązań działa; różnią się jedynie ilością kodu konfiguracyjnego.
+
+Ta warstwa jest niezbędna, lecz niewystarczająca. Typy opisują kształt Twojego katalogu domyślnego. Nie informują jednak, czy w języku koreańskim istnieje wartość dla danego klucza.
+
+## Warstwa 2: sprawdzaj linterem teksty, które nigdy nie stały się kluczami
+
+Tłumaczenie, którego nie możesz znaleźć, to często to, które nigdy nie zostało wyodrębnione. Etykieta wpisana na sztywno w komponencie jest niewidoczna dla każdego audytu katalogów, ponieważ z perspektywy narzędzi po prostu nie istnieje.
+
+Wtyczka ESLint dla Intlayer rozwiązuje ten problem regułą `no-raw-text`, uzupełnioną o `no-unused-content` dla sytuacji odwrotnej: treści zadeklarowanej, z której nic już nie korzysta.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` zapobiega niekontrolowanemu rozrastaniu się katalogów. Martwe klucze nie psują działania aplikacji, ale niepotrzebnie powiększają rachunki za tłumaczenia. Pełna lista reguł znajduje się w [dokumentacji wtyczki ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/eslint.md).
+
+## Warstwa 3: audyt pokrycia języków
+
+To warstwa, która bezpośrednio odpowiada na właściwe pytanie. Intlayer dostarcza ją jako polecenie CLI:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Polecenie odczytuje skonfigurowane języki i zadeklarowane słowniki, po czym zgłasza, którym kluczom brakuje tłumaczeń, w jakich językach i w jakim pliku.
+
+Ważny szczegół przed włączeniem tego do procesów CI: **CLI drukuje raport, ale kończy działanie z kodem wyjścia 0.** Jeśli dodasz je do potoku, oczekując przerwania buildu, otrzymasz zielony build z długim raportem tekstowym, którego nikt nie przeczyta. Do blokowania kompilacji użyj programistycznego API opisanego poniżej.
+
+## Warstwa 4: asercje w zestawie testów
+
+`listMissingTranslations()` zwraca dokładnie ten sam audyt w formie ustrukturyzowanych danych, co idealnie nadaje się do stworzenia bramki kompilacji (build gate).
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("has no missing required locales", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Zwracane są trzy pola o istotnym znaczeniu:
+
+- `missingTranslations`: w rozbiciu na klucze, jakich języków brakuje i w jakim pliku. To właśnie te dane drukujesz w przypadku błędu testu.
+- `missingLocales`: suma wszystkich brakujących języków we wszystkich kluczach.
+- `missingRequiredLocales`: ograniczone do `requiredLocales` z Twojej konfiguracji (lub wszystkie języki, jeśli opcja nie została zdefiniowana).
+
+## `requiredLocales` sprawia, że bramka jest znośna w praktyce
+
+Wydawanie aplikacji w osiemnastu językach nie oznacza, że wszystkie osiemnaście musi być w 100% gotowych, aby móc wdrożyć kod. Większość zespołów posiada poziom krytyczny, który blokuje wydanie, oraz poziom uzupełniany na bieżąco.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Bez `requiredLocales` każdy zadeklarowany język jest bezwzględnie wymagany, a Twój build pozostanie czerwony, dopóki nie spłynie ostatnie tłumaczenie. W rezultacie zespoły najczęściej całkowicie wyłączają tę weryfikację, co jest gorsze niż brak jakichkolwiek testów.
+
+## Wykrywanie braków, które już trafiły na produkcję
+
+Powyższe warstwy chronią przed nowymi lukami. W przypadku aplikacji, która już działa na produkcji, pomagają dwie techniki.
+
+**Pseudolokalizacja.** Uruchom aplikację ze sztucznym językiem, w którym każdy ciąg znaków jest zmodyfikowany, na przykład `[!!! Ĉĥéçķöũţ !!!]`. Wszystko, co nadal wyświetla się po angielsku, jest zaszyte w kodzie na stałe. Pozwala to w dziesięć minut wykryć to, czego audyt katalogów strukturalnie nie jest w stanie zobaczyć, ponieważ testuje wyrenderowaną stronę, a nie same pliki z danymi.
+
+**Crawlowanie własnej witryny.** Jeśli używasz zlokalizowanych adresów URL, pobierz próbkę podstron dla każdego języka i przeszukaj kod HTML pod kątem ciągów znaków z języka domyślnego. Strona w `/ja/` zawierająca zwrot "Add to cart" to albo brakujące tłumaczenie, albo nieoczekiwany fallback.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Uzupełnianie luk
+
+Gdy wiesz już, czego brakuje, `intlayer fill` uzupełnia puste wpisy, a opcja `autoFill` potrafi generować pliki dla poszczególnych języków bezpośrednio podczas deklarowania zawartości. Zobacz [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/autoFill.md).
+
+Warto spojrzeć na to trzeźwym okiem: automatyczne uzupełnianie maszynowe zamienia lukę _widoczną_ w lukę _niewidoczną_. Klucz ma teraz wartość, audyt świeci na zielono, ale nikt nie sprawdził sensu sformułowań. Używaj tego do odblokowania release'u, a następnie przekazuj teksty do weryfikacji człowiekowi w przypadku wszystkiego, co klient czyta przed podjęciem decyzji. To rusztowanie pomocnicze, a nie gotowy produkt.
+
+## Częste błędy
+
+- **Traktowanie mechanizmu fallback jako tarczy bezpieczeństwa.** To strategia renderowania awaryjnego, a nie siatka ochronna. Cicho wyświetlana angielska strona to błąd, którego nikt nie zgłasza.
+- **Poleganie na raporcie CLI do blokowania CI.** `intlayer content test` kończy się kodem zero. Wymagaj asercji w teście.
+- **Wymaganie absolutnie każdego języka.** Kontrola zostaje usunięta przy pierwszym zablokowanym wydaniu.
+- **Audytowanie wyłącznie katalogów, a nigdy wyrenderowanego ekranu.** Teksty zaszyte w kodzie są z definicji niewidoczne w katalogach.
+- **Testowanie tylko języka domyślnego.** To jedyny język, którego na pewno nigdy nie zabraknie.
+- **Kończenie procesu na automatycznym wypełnieniu.** Zielony audyt przy niezweryfikowanych tekstach.
+
+## Warto przeczytać
+
+- [Testowanie treści: audyt CLI, programistyczne API i asercje UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/testing.md)
+- [Reguły wtyczki ESLint, w tym `no-raw-text` i `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/eslint.md)
+- [autoFill: generowanie plików deklaracji dla poszczególnych języków](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/autoFill.md)
+- [Dokumentacja konfiguracji: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Raporty benchmarkowe porównujące frameworki](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md)
+- [Adapter kompatybilności i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/i18next.md)
+- [Co w rzeczywistości obejmuje internacjonalizacja](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/what_is_internationalization.md)
+- [i18n na poziomie komponentów a podejście scentralizowane](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/per-component_vs_centralized_i18n.md)

package/blog/pl/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Automatyzacja tłumaczeń w CI/CD bez publikowania złych tekstów"
+description: Trzy miejsca na automatyzację i18n, pre-push, pull request i runtime. Jak blokować build na podstawie pokrycia, bezpiecznie uzupełniać braki i unikać nieskończonej pętli commitów w CI.
+keywords:
+  - automatyzacja tłumaczeń ci
+  - i18n ci cd
+  - github actions tłumaczenia
+  - husky pre-push
+  - ciągła lokalizacja
+  - pipeline tłumaczeń
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Automatyzacja tłumaczeń w CI/CD bez publikowania złych tekstów
+
+Ręczne tłumaczenie nie wytrzymuje zderzenia z nowoczesnym cyklem wydawniczym. Ktoś dodaje ciąg znaków w piątek, eksport następuje w kolejnym sprincie, a do tego czasu trzy kolejne języki pozostają w tyle. Sama automatyzacja jest prosta. Jednak zautomatyzowanie procesu bez cichego publikowania maszynowych tekstów do klientów to kwestia, nad którą warto się zastanowić.
+
+## Spis treści
+
+<TOC/>
+
+## Nie musisz migrować, aby zautomatyzować
+
+Poniższe struktury pipeline'ów są niezależne od biblioteki, podobnie jak same narzędzia. Jeśli Twoje wiadomości to katalogi JSON dla i18next, next-intl, react-intl, vue-i18n lub next-translate, [wtyczka Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-json.md) odczytuje i zapisuje te pliki bezpośrednio w miejscu:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // lub "icu" dla next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Twoja aplikacja nadal importuje to, co importowała dotychczas. Poniższe zadania CI uzupełniają i weryfikują istniejące katalogi, a diff widoczny dla recenzenta to zmiana w `locales/fr/checkout.json`, a nie duża migracja kodu. Dostępna jest również [wtyczka Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-po.md) dla przepływów gettext oraz [adaptery kompatybilności](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md), jeśli zależy Ci na zachowaniu obecnego runtime API.
+
+## Oddziel bramkę (gate) od uzupełniania (fill)
+
+Dwa zupełnie różne zadania są nagminnie mylone.
+
+**Bramka (gate)** to kontrola, która zgłasza błąd. Oznacza, że ta kompilacja nie może trafić na produkcję, ponieważ brakuje wymaganych tłumaczeń. Bramka niczego nie zapisuje.
+
+**Uzupełnianie (fill)** to operacja modyfikacji. Generuje brakujące tłumaczenia i tworzy commit. Nigdy nie przerywa buildu z błędem.
+
+Uruchamianie samego uzupełniania oznacza, że nic nigdy nie blokuje wdrożenia, a niesprawdzone tłumaczenia maszynowe trafiają do użytkowników. Uruchamianie samej bramki sprawia, że build staje się czerwony i człowiek musi za każdym razem ręcznie interweniować. Większość zespołów potrzebuje obu mechanizmów powiązanych z różnymi zdarzeniami: fill przy pull requeście, gate przy merge do gałęzi wydaniowej.
+
+## Gdzie można umieścić automatyzację
+
+| Etap          | Wyzwalacz   | Dobre do                                    | Koszt                                            |
+| :------------ | :---------- | :------------------------------------------ | :----------------------------------------------- |
+| Hook pre-push | Lokalny git | Szybka informacja zwrotna, zero minut w CI  | Działa na maszynie programisty i jego kluczu API |
+| Pull request  | Zadanie CI  | Przegląd przed merge, bezpieczne sekrety    | Minuty w CI oraz wywołania modeli na każdy PR    |
+| Gałąź wydania | Zadanie CI  | Twarda bramka pokrycia                      | Tanie, brak zapytań do modeli                    |
+| Runtime       | CMS         | Zmiany treści bez przebudowywania aplikacji | Zależność od zewnętrznej usługi                  |
+
+## Pre-push: najszybsza pętla
+
+Husky uruchamia uzupełnianie, zanim kod opuści lokalną maszynę, dzięki czemu tłumaczenia trafiają do tego samego pusha co nowe ciągi znaków.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` ogranicza pracę do treści, które nie zostały jeszcze wypchnięte do repozytorium, co zapobiega minutowym opóźnieniom przy każdym pushu. `--mode complete` wypełnia tylko brakujące wpisy bez przepisywania tych, które już mają wartość, dzięki czemu zweryfikowane tłumaczenie nigdy nie zostanie po cichu zastąpione.
+
+W przypadku monorepo zawęź zakres do poszczególnych aplikacji:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Minus jest oczywisty: każdy programista potrzebuje klucza API, a koszt spada na osobę wykonującą push. Dlatego w miarę rozwoju zespołu większość projektów przenosi ten etap do CI.
+
+## Pull request: uzupełnianie w miejscu recenzji
+
+Ta sama praca w GitHub Actions, zawężona do diffa:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Cztery szczegóły mają tu kluczowe znaczenie:
+
+- **`fetch-depth: 0`** jest niezbędne do działania `--git-diff`. Płytki klon nie ma bazy do wyliczenia różnic i uzupełnianie niczego nie wykona.
+- **`[skip ci]` w wiadomości commita** zapobiega zapętleniu workflow. Bez tego commit uruchamia nowy przebieg, który znów commituje, drenując limit CI w jedną noc.
+- **`concurrency` z `cancel-in-progress`** zatrzymuje równoległe pushe przed jednoczesnym zapisem do tych samych plików.
+- **`--git-diff`** ogranicza działanie do zmian w PR. Pominięcie tego spowoduje ponowne tłumaczenie całego katalogu przy każdym uruchomieniu.
+
+Tłumaczenia pojawiają się jako commit w gałęzi PR, co oznacza, że recenzent widzi je w diffie. To główny powód, dla którego warto to robić tutaj, a nie po wykonaniu merge.
+
+## Gałąź wydaniowa: bramka (gate)
+
+Bramka nie potrzebuje dostępu do modeli i powinna działać błyskawicznie.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Wspierana testem sprawdzającym pokrycie zamiast polegania na samym raporcie CLI:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` drukuje raport, ale kończy się z kodem 0, więc informuje, ale nie blokuje. Używaj tego lokalnie, a w CI polegaj na asercjach w teście. Więcej szczegółów w [wykrywaniu brakujących tłumaczeń](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/detecting_missing_translations.md).
+
+## `requiredLocales` czyni bramkę znośną w praktyce
+
+Bramka wymagająca kompletności wszystkich osiemnastu języków blokuje każde wydanie do czasu przygotowania najwolniejszego tłumaczenia i zostaje wyłączona w ciągu miesiąca.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Zadeklaruj obsługiwane języki i wymagaj jako blokujące tylko te, które są krytyczne dla wydania. Reszta jest uzupełniana asynchronicznie i nie opóźnia wdrożeń.
+
+## Całkowite wyniesienie tłumaczeń poza repozytorium
+
+Alternatywnym podejściem jest zadeklarowanie jednego języka w kodzie i zarządzanie pozostałymi zdalnie za pośrednictwem CMS z Live Sync. Zmiany treści nie wymagają wtedy ponownej kompilacji, co oddziela tempo prac edytorskich od cyklu wdrożeń programistycznych.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Odpowiada to zespołom, w których treścią zajmują się osoby nietechniczne. Jest to kompromis: zyskujesz autonomię edytorską, ale tracisz pewność, że checkout gita w pełni opisuje stan renderowania aplikacji. Szczegóły w [dokumentacji CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md).
+
+Pamiętaj, że `clientSecret` to poświadczenie serwerowe. Powinno znajdować się w sekretach CI i środowisku serwera, nigdy w kodzie klienta.
+
+## Rzeczywiste ograniczenia
+
+Wszystko powyżej automatyzuje _pokrycie_, a nie _jakość_. Maszynowe uzupełnienie zamienia widoczną lukę w lukę niewidoczną: audyt świeci na zielono, ponieważ klucz ma wartość, ale nikt jej nie przeczytał.
+
+Jest to dopuszczalne w przypadku narzędzi wewnętrznych, changelogów czy języków w wersji beta. Nie jest to akceptowalne dla cenników, tekstów prawnych, komunikatów o błędach płatności ani niczego, co klient czyta przed podjęciem decyzji. Skieruj te teksty do człowieka i używaj `--mode complete`, aby zweryfikowane ciągi nie zostały nadpisane.
+
+Dostarcz modelowi kontekst, aby jego wyniki były spójne:
+
+```ts
+ai: {
+  applicationContext: "Aplikacja do fakturowania B2B. Styl formalny. Nigdy nie tłumacz nazwy produktu.",
+}
+```
+
+## Częste błędy
+
+- **Brak `[skip ci]` w automatycznym commicie.** Zadanie zapętla się bez końca.
+- **Płytki klon z `--git-diff`.** Brak bazy do porównania skutkuje cichym brakiem działań.
+- **Uzupełnianie całego katalogu przy każdym uruchomieniu.** Ograniczaj zakres za pomocą `--git-diff` lub `--unpushed`.
+- **Używanie raportu CLI jako bramki.** Zwraca kod 0 i nie przerywa buildu.
+- **Wymaganie każdego języka.** Kontrola zostaje wyłączona przy pierwszym zablokowanym wydaniu.
+- **Zadanie uzupełniania bez żadnej bramki.** Nic nie zgłasza błędów, a niesprawdzone teksty trafiają na produkcję.
+- **Klucze API modeli w repozytorium.** Powinny być w sekretach CI, podobnie jak `clientSecret`.
+
+## Warto przeczytać
+
+- [CI/CD: automatyczne generowanie tłumaczeń z Husky, GitHub Actions i CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/CI_CD.md)
+- [Testowanie treści i blokowanie buildu na podstawie pokrycia](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/testing.md)
+- [autoFill: generowanie plików deklaracji dla poszczególnych języków](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/autoFill.md)
+- [Dokumentacja konfiguracji: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Raporty porównawcze wydajności między frameworkami](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md)
+- [Adapter kompatybilności i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/i18next.md)
+- [Jak wykrywać brakujące tłumaczenia](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/detecting_missing_translations.md)
+- [Jak testować tłumaczenia bez kruchych testów](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/i18n_testing_strategies.md)