@intlayer/docs 7.0.7 → 7.0.8

package/docs/pl/intlayer_with_express.md

@@ -0,0 +1,411 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Jak przetłumaczyć backend Express – przewodnik i18n 2025
+description: Dowiedz się, jak uczynić swój backend vite wielojęzycznym. Postępuj zgodnie z dokumentacją, aby internacjonalizować (i18n) i tłumaczyć.
+keywords:
+  - Internacjonalizacja
+  - Dokumentacja
+  - Intlayer
+  - Express
+  - JavaScript
+  - Backend
+slugs:
+  - doc
+  - environment
+  - express
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inicjalizacja historii
+---
+
+# Tłumaczenie backendu Express za pomocą Intlayer | Internacjonalizacja (i18n)
+
+`express-intlayer` to potężne middleware do internacjonalizacji (i18n) dla aplikacji Express, zaprojektowane, aby uczynić Twoje usługi backendowe globalnie dostępnymi poprzez dostarczanie zlokalizowanych odpowiedzi na podstawie preferencji klienta.
+
+### Praktyczne zastosowania
+
+- **Wyświetlanie błędów backendu w języku użytkownika**: Gdy wystąpi błąd, wyświetlanie komunikatów w ojczystym języku użytkownika poprawia zrozumienie i zmniejsza frustrację. Jest to szczególnie przydatne dla dynamicznych komunikatów o błędach, które mogą być wyświetlane w komponentach front-end, takich jak toasty czy modale.
+
+- **Pobieranie treści wielojęzycznych**: W przypadku aplikacji pobierających treści z bazy danych, internacjonalizacja zapewnia możliwość serwowania tych treści w wielu językach. Jest to kluczowe dla platform takich jak sklepy internetowe czy systemy zarządzania treścią, które muszą wyświetlać opisy produktów, artykuły i inne treści w preferowanym przez użytkownika języku.
+
+- **Wysyłanie wielojęzycznych e-maili**: Niezależnie od tego, czy są to e-maile transakcyjne, kampanie marketingowe, czy powiadomienia, wysyłanie wiadomości w języku odbiorcy może znacznie zwiększyć zaangażowanie i skuteczność.
+
+- **Wielojęzyczne powiadomienia push**: W przypadku aplikacji mobilnych, wysyłanie powiadomień push w preferowanym przez użytkownika języku może poprawić interakcję i retencję. Ten osobisty akcent sprawia, że powiadomienia wydają się bardziej istotne i angażujące.
+
+- **Inne formy komunikacji**: Każda forma komunikacji z backendu, taka jak wiadomości SMS, alerty systemowe czy aktualizacje interfejsu użytkownika, zyskuje na tym, że jest w języku użytkownika, co zapewnia jasność i poprawia ogólne doświadczenie użytkownika.
+
+Poprzez internacjonalizację backendu, Twoja aplikacja nie tylko szanuje różnice kulturowe, ale także lepiej dostosowuje się do potrzeb globalnego rynku, co stanowi kluczowy krok w skalowaniu usług na całym świecie.
+
+## Pierwsze kroki
+
+### Instalacja
+
+Aby rozpocząć korzystanie z `express-intlayer`, zainstaluj pakiet za pomocą npm:
+
+```bash packageManager="npm"
+npm install intlayer express-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer express-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer express-intlayer
+```
+
+### Konfiguracja
+
+Skonfiguruj ustawienia internacjonalizacji, tworząc plik `intlayer.config.ts` w katalogu głównym projektu:
+
+```typescript fileName="intlayer.config.ts"  codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+### Zadeklaruj swoją zawartość
+
+Twórz i zarządzaj deklaracjami zawartości, aby przechowywać tłumaczenia:
+
+```typescript fileName="src/index.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+} satisfies Dictionary;
+
+export default indexContent;
+```
+
+```javascript fileName="src/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+};
+
+export default indexContent;
+```
+
+```javascript fileName="src/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      en: "Example of returned content in English",
+      pl: "Przykład zwróconej zawartości w języku angielskim",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+};
+
+module.exports = indexContent;
+```
+
+```json fileName="src/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "index",
+  "content": {
+    "exampleOfContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Example of returned content in English",
+        "pl": "Przykład zwróconej zawartości w języku angielskim",
+        "fr": "Exemple de contenu renvoyé en français",
+        "es-ES": "Ejemplo de contenido devuelto en español (España)",
+        "es-MX": "Ejemplo de contenido devuelto en español (México)"
+      }
+    }
+  }
+}
+```
+
+> Twoje deklaracje zawartości mogą być definiowane w dowolnym miejscu w Twojej aplikacji, pod warunkiem, że są umieszczone w katalogu `contentDir` (domyślnie `./src`). I mają rozszerzenie pliku deklaracji zawartości (domyślnie `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+
+> Aby uzyskać więcej szczegółów, zapoznaj się z [dokumentacją deklaracji zawartości](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md).
+
+### Konfiguracja aplikacji Express
+
+Skonfiguruj swoją aplikację Express, aby korzystała z `express-intlayer`:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";
+import dictionaryExample from "./index.content";
+
+const app: Express = express();
+
+// Załaduj handler żądań internacjonalizacji
+app.use(intlayer());
+
+// Trasy
+app.get("/t_example", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    })
+  );
+});
+
+app.get("/getIntlayer_example", (_req, res) => {
+  res.send(getIntlayer("index").exampleOfContent);
+});
+
+app.get("/getDictionary_example", (_req, res) => {
+  res.send(getDictionary(dictionaryExample).exampleOfContent);
+});
+
+// Uruchom serwer
+app.listen(3000, () => console.log(`Nasłuchiwanie na porcie 3000`));
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = express();
+
+// Załaduj handler żądań internacjonalizacji
+app.use(intlayer());
+
+// Trasy
+app.get("/t_example", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    })
+  );
+});
+
+app.get("/getIntlayer_example", (_req, res) => {
+  res.send(getIntlayer("index").exampleOfContent);
+});
+
+app.get("/getDictionary_example", (_req, res) => {
+  res.send(getDictionary(dictionaryExample).exampleOfContent);
+});
+
+// Uruchom serwer
+app.listen(3000, () => console.log(`Nasłuchiwanie na porcie 3000`));
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer, t, getDictionary, getIntlayer } = require("express-intlayer");
+const dictionaryExample = require("./index.content");
+
+const app = express();
+
+// Załaduj handler żądań internacjonalizacji
+app.use(intlayer());
+
+// Trasy
+app.get("/t_example", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    })
+  );
+});
+
+app.get("/getIntlayer_example", (_req, res) => {
+  res.send(getIntlayer("index").exampleOfContent);
+});
+
+app.get("/getDictionary_example", (_req, res) => {
+  res.send(getDictionary(dictionaryExample).exampleOfContent);
+});
+
+// Uruchom serwer
+app.listen(3000, () => console.log(`Nasłuchiwanie na porcie 3000`));
+```
+
+### Kompatybilność
+
+`express-intlayer` jest w pełni kompatybilny z:
+
+- [`react-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/index.md) dla aplikacji React
+- [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/next-intlayer/index.md) dla aplikacji Next.js
+- [`vite-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/vite-intlayer/index.md) dla aplikacji Vite
+
+Działa również bezproblemowo z dowolnym rozwiązaniem do internacjonalizacji w różnych środowiskach, w tym w przeglądarkach i zapytaniach API. Możesz dostosować middleware, aby wykrywać lokalizację za pomocą nagłówków lub ciasteczek:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Inne opcje konfiguracji
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Inne opcje konfiguracji
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Inne opcje konfiguracji
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+module.exports = config;
+```
+
+Domyślnie `express-intlayer` będzie interpretować nagłówek `Accept-Language`, aby określić preferowany język klienta.
+
+> Aby uzyskać więcej informacji na temat konfiguracji i zaawansowanych zagadnień, odwiedź naszą [dokumentację](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
+
+### Konfiguracja TypeScript
+
+`express-intlayer` wykorzystuje zaawansowane możliwości TypeScript, aby usprawnić proces internacjonalizacji. Statyczne typowanie w TypeScript zapewnia, że każdy klucz tłumaczenia jest uwzględniony, co zmniejsza ryzyko brakujących tłumaczeń i poprawia utrzymanie kodu.
+
+![Autouzupełnianie](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Błąd tłumaczenia](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Upewnij się, że automatycznie generowane typy (domyślnie w ./types/intlayer.d.ts) są uwzględnione w Twoim pliku tsconfig.json.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Twoje istniejące konfiguracje TypeScript
+  "include": [
+    // ... Twoje istniejące konfiguracje TypeScript
+    ".intlayer/**/*.ts", // Dołącz automatycznie generowane typy
+  ],
+}
+```
+
+### Rozszerzenie VS Code
+
+Aby poprawić doświadczenie programistyczne z Intlayer, możesz zainstalować oficjalne **rozszerzenie Intlayer dla VS Code**.
+
+[Zainstaluj z VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+To rozszerzenie oferuje:
+
+- **Autouzupełnianie** kluczy tłumaczeń.
+- **Wykrywanie błędów w czasie rzeczywistym** dla brakujących tłumaczeń.
+- **Podglądy w linii** przetłumaczonej zawartości.
+- **Szybkie akcje** do łatwego tworzenia i aktualizowania tłumaczeń.
+
+Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z [dokumentacją rozszerzenia Intlayer VS Code](https://intlayer.org/doc/vs-code-extension).
+
+### Konfiguracja Git
+
+Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania do repozytorium Git.
+
+Aby to zrobić, możesz dodać następujące instrukcje do pliku `.gitignore`:
+
+```plaintext fileName=".gitignore"
+# Ignoruj pliki generowane przez Intlayer
+.intlayer
+```