@intlayer/docs 7.0.7 → 7.0.8-canary.0

package/docs/pl/packages/react-intlayer/useLocale.md

@@ -0,0 +1,210 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Dokumentacja hooka useLocale | react-intlayer
+description: Zobacz, jak używać hooka useLocale w pakiecie react-intlayer
+keywords:
+  - useLocale
+  - słownik
+  - klucz
+  - Intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useLocale
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inicjalizacja historii
+---
+
+# Integracja z React: Dokumentacja hooka `useLocale`
+
+Ta sekcja zawiera szczegółowe informacje o hooku `useLocale` z biblioteki `react-intlayer`, zaprojektowanym do zarządzania lokalizacją w aplikacjach React.
+
+## Importowanie `useLocale` w React
+
+Aby zintegrować hook `useLocale` z aplikacją React, zaimportuj go z odpowiedniego pakietu:
+
+```typescript codeFormat="typescript"
+import { useLocale } from "react-intlayer"; // Używane w komponentach React do zarządzania lokalizacją
+```
+
+```javascript codeFormat="esm"
+import { useLocale } from "react-intlayer"; // Używane w komponentach React do zarządzania lokalizacją
+```
+
+```javascript codeFormat="commonjs"
+const { useLocale } = require("react-intlayer"); // Używane w komponentach React do zarządzania lokalizacją
+```
+
+## Przegląd
+
+Hook `useLocale` oferuje prosty sposób na dostęp i manipulację ustawieniami lokalizacji w komponentach React. Zapewnia dostęp do bieżącej lokalizacji, domyślnej lokalizacji, wszystkich dostępnych lokalizacji oraz funkcji do aktualizacji ustawień lokalizacji.
+
+## Użycie
+
+Oto jak można użyć hooka `useLocale` w komponencie React:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Aktualna lokalizacja: {locale}</h1>
+      <p>Domyślna lokalizacja: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Aktualna lokalizacja: {locale}</h1>
+      <p>Domyślna lokalizacja: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Aktualna lokalizacja: {locale}</h1>
+      <p>Domyślna lokalizacja: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+## Parametry i wartości zwracane
+
+Gdy wywołujesz hook `useLocale`, zwraca on obiekt zawierający następujące właściwości:
+
+- **`locale`**: Aktualna lokalizacja ustawiona w kontekście React.
+- **`defaultLocale`**: Główna lokalizacja zdefiniowana w konfiguracji.
+- **`availableLocales`**: Lista wszystkich dostępnych lokalizacji zdefiniowanych w konfiguracji.
+- **`setLocale`**: Funkcja do aktualizacji bieżącej lokalizacji w kontekście aplikacji.
+
+## Przykład
+
+Ten przykład pokazuje komponent, który używa hooka `useLocale` do renderowania przełącznika lokalizacji, pozwalającego użytkownikom dynamicznie zmieniać lokalizację aplikacji:
+
+```tsx fileName="src/components/LocaleSelector.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector: FC = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+## Podsumowanie
+
+Hook `useLocale` z pakietu `react-intlayer` jest niezbędnym narzędziem do zarządzania lokalizacjami w Twoich aplikacjach React, zapewniając funkcjonalność potrzebną do skutecznego dostosowania aplikacji do różnych międzynarodowych odbiorców.

package/docs/pl/per_locale_file.md

@@ -0,0 +1,321 @@
+---
+createdAt: 2025-04-18
+updatedAt: 2025-06-29
+title: Deklaracja zawartości `Per-Locale` w Intlayer
+description: Dowiedz się, jak deklarować zawartość per locale w Intlayer. Postępuj zgodnie z dokumentacją, aby zrozumieć różne formaty i przypadki użycia.
+keywords:
+  - Internacjonalizacja
+  - Dokumentacja
+  - Intlayer
+  - Per-Locale
+  - TypeScript
+  - JavaScript
+slugs:
+  - doc
+  - concept
+  - per-locale-file
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inicjalizacja historii
+---
+
+# Deklaracja zawartości `Per-Locale` w Intlayer
+
+Intlayer obsługuje dwa sposoby deklarowania wielojęzycznej zawartości:
+
+- Jeden plik ze wszystkimi tłumaczeniami
+- Jeden plik na locale (format per-locale)
+
+Ta elastyczność umożliwia:
+
+- Łatwą migrację z innych narzędzi i18n
+- Wsparcie dla zautomatyzowanych procesów tłumaczeniowych
+- Jasna organizacja tłumaczeń w oddzielnych plikach specyficznych dla locale
+
+## Jeden plik z wieloma tłumaczeniami
+
+Ten format jest idealny dla:
+
+- Szybkiej iteracji w kodzie.
+- Bezproblemowej integracji z CMS.
+
+Jest to zalecane podejście dla większości przypadków użycia. Centralizuje tłumaczenia, co ułatwia iterację i integrację z CMS.
+
+```tsx fileName="hello-world.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.cjs" contentDeclarationFormat="json"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Title of my component",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+> Zalecane: Ten format jest najlepszy podczas korzystania z wizualnego edytora Intlayer lub zarządzania tłumaczeniami bezpośrednio w kodzie.
+
+## Format per-locale
+
+Ten format jest przydatny, gdy:
+
+- Chcesz wersjonować lub nadpisywać tłumaczenia niezależnie.
+- Integrujesz procesy tłumaczeń maszynowych lub ludzkich.
+
+Możesz również podzielić tłumaczenia na indywidualne pliki dla poszczególnych lokalizacji, określając pole locale:
+
+```tsx fileName="hello-world.en.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Ważne
+  content: { multilingualContent: "Title of my component" },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Ważne
+  content: { multilingualContent: "Título de mi componente" },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.en.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+// Definicja słownika treści dla komponentu "hello-world"
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Ważne
+  content: { multilingualContent: "Title of my component" },
+};
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+// Definicja słownika treści dla komponentu "hello-world" w języku hiszpańskim
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Ważne
+  content: { multilingualContent: "Título de mi componente" },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.en.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Ważne
+  content: {
+    multilingualContent: "Title of my component",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Ważne
+  content: {
+    multilingualContent: "Título de mi componente",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "en", // Ważne
+  "content": {
+    "multilingualContent": "Tytuł mojego komponentu",
+  },
+}
+```
+
+```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "es", // Ważne
+  "content": {
+    "multilingualContent": "Título de mi componente",
+  },
+}
+```
+
+> Ważne: Upewnij się, że pole locale jest zdefiniowane. Informuje Intlayer, jakiego języka dotyczy plik.
+
+> Uwaga: W obu przypadkach plik deklaracji zawartości musi mieć nazwę zgodną z wzorcem `*.content.{ts,tsx,js,jsx,mjs,cjs,json}`, aby został rozpoznany przez Intlayer. Sufiks `.[locale]` jest opcjonalny i służy tylko jako konwencja nazewnicza.
+
+## Mieszanie formatów
+
+Możesz łączyć oba podejścia deklaracji dla tego samego klucza zawartości. Na przykład:
+
+- Zadeklaruj swoją bazową zawartość statycznie w pliku takim jak index.content.ts.
+- Dodaj lub nadpisz konkretne tłumaczenia w osobnych plikach, takich jak index.fr.content.ts lub index.content.json.
+
+To rozwiązanie jest szczególnie przydatne, gdy:
+
+- Chcesz zdefiniować początkową strukturę zawartości w kodzie.
+- Planujesz wzbogacić lub uzupełnić tłumaczenia później, korzystając z CMS lub narzędzi automatycznych.
+
+```bash codeFormat="typescript"
+.
+└── Components
+    └── MyComponent
+        ├── index.content.ts
+        ├── index.content.json
+        └── index.ts
+```
+
+### Przykład
+
+Oto plik deklaracji zawartości wielojęzycznej:
+
+```tsx fileName="Components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH,
+  content: {
+    multilingualContent: "Tytuł mojego komponentu",
+    projectName: "Mój projekt",
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```json fileName="Components/MyComponent/index.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Titre de mon composant",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+Intlayer automatycznie łączy pliki wielojęzyczne i per-locale.
+
+```tsx fileName="Components/MyComponent/index.ts"
+import { getIntlayer, Locales } from "intlayer";
+
+const intlayer = getIntlayer("hello-world"); // Domyślny język to ENGLISH, więc zwróci zawartość w języku angielskim
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Wynik:
+// {
+//  "multilingualContent": "Tytuł mojego komponentu",
+//  "projectName": "Mój projekt"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.SPANISH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Wynik:
+// {
+//  "multilingualContent": "Título de mi componente",
+//  "projectName": "Mój projekt"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.FRENCH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Wynik:
+// {
+//  "multilingualContent": "Titre de mon composant",
+//  "projectName": "Mój projekt"
+// }
+```
+
+### Automatyczne generowanie tłumaczeń
+
+Użyj [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_cli.md), aby automatycznie uzupełnić brakujące tłumaczenia na podstawie wybranych usług.