@intlayer/docs 5.5.9 → 5.5.11

package/frequent_questions/de/get_locale_cookie.md

@@ -0,0 +1,143 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Wie man die Locale aus Cookies / Headern ausliest
+description: Lernen Sie, wie man die Locale aus Cookies / Headern ausliest.
+keywords:
+  - cookie
+  - header
+  - intlayer
+  - locale
+  - hook
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# Wie man die Locale aus Cookies / Headern ausliest
+
+## Verwendung von Hooks (Empfohlen)
+
+Für die meisten Anwendungsfälle wird empfohlen, die aktuelle Locale mit dem `useLocale` Hook auszulesen, da dieser automatisch aufgelöst wird. Dies funktioniert ähnlich wie der `useLocale` Composable in Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// oder import { useLocale } von "react-intlayer";
+// oder import { useLocale } von "vue-intlayer";
+
+// Client-seitige Verwendung
+const { locale } = useLocale();
+```
+
+Für Server-Komponenten können Sie es importieren von:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+Es gibt auch einen `useLocaleCookie` Hook, der nur den Cookie-Wert auflöst.
+
+## Manuelle Cookie-Konfiguration
+
+Sie können einen benutzerdefinierten Cookie-Namen deklarieren als
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // Standard ist 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+das Abrufen erfolgt wie folgt
+
+### Client-seitig
+
+```ts
+// Verwendung des Standard-Cookie-Namens
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Verwendung eines benutzerdefinierten Cookie-Namens
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### Server-seitig (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Verwendung des Standard-Cookie-Namens
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Verwendung eines benutzerdefinierten Cookie-Namens
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### Falls die Locale noch nicht gesetzt ist
+
+Die Locale wird als Cookie nur gesetzt, wenn der Benutzer die Locale explizit auswählt. Standardmäßig wird für neue Besucher die Locale aus den Header-Feldern interpretiert.
+
+Sie können die bevorzugte Locale des Benutzers aus den Anforderungsheadern erkennen. Hier ist ein Beispiel, wie dies gehandhabt wird:
+
+```ts
+/**
+ * Erkennt die Locale aus den Anforderungsheadern
+ *
+ * Der accept-language Header ist der wichtigste für die Locale-Erkennung.
+ * Er enthält eine Liste von Sprachcodes mit Qualitätswerten (q-Werten), die
+ * die bevorzugten Sprachen des Benutzers in der Reihenfolge der Präferenz angeben.
+ *
+ * Beispiel: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US ist die primäre Sprache (q=1.0 ist impliziert)
+ * - en ist die zweite Wahl (q=0.9)
+ * - fr ist die dritte Wahl (q=0.8)
+ * - es ist die vierte Wahl (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Beispiel für Negotiator-Header, die Browser typischerweise senden
+ * Diese Header helfen dabei, die bevorzugte Sprache des Benutzers zu bestimmen
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Anwendungsbeispiel:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/de/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Intlayer-Befehl nicht definiert
+description: Erfahren Sie, wie Sie den Fehler "intlayer command undefined" beheben können.
+keywords:
+  - intlayer
+  - befehl
+  - undefiniert
+  - fehler
+  - vscode
+  - erweiterung
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - intlayer-befehl-nicht-definiert
+---
+
+# Intlayer-Befehl nicht definiert
+
+## Übersicht
+
+Die Intlayer-CLI bietet eine bequeme Möglichkeit, Ihre Intlayer-Inhalte zu verwalten, einschließlich dem Erstellen von Wörterbüchern, dem Übertragen von Übersetzungen und mehr. Sie ist jedoch nicht zwingend erforderlich, damit Ihr Projekt funktioniert. Wenn Sie das Bundler-Plugin verwenden (wie `withIntlayer()` für Next.js oder `intlayerPlugin()` für Vite), erstellt Intlayer automatisch Wörterbücher während des App-Builds oder beim Start des Entwicklungsservers. Im Entwicklungsmodus überwacht es außerdem Änderungen und erstellt die Inhaltsdeklarationsdateien automatisch neu.
+
+Sie können auf die Intlayer-Befehle auf verschiedene Weise zugreifen:
+
+- Direkt über den `intlayer` CLI-Befehl
+- Über die [VSCode-Erweiterung](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/vs_code_extension.md)
+- Über das `@intlayer/cli` SDK
+
+## Problem
+
+Beim Versuch, den Befehl `intlayer` zu verwenden, kann folgende Fehlermeldung auftreten:
+
+```bash
+'intlayer' wird nicht als interner oder externer Befehl,
+programmierbares Programm oder Batchdatei erkannt.
+```
+
+## Lösungen
+
+Versuchen Sie diese Lösungen in der angegebenen Reihenfolge:
+
+1. **Überprüfen Sie, ob der Befehl installiert ist**
+
+```bash
+npx intlayer -h
+```
+
+Erwartete Ausgabe:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            gibt die Versionsnummer aus
+    -h, --help               zeigt die Hilfe für den Befehl an
+
+Commands:
+    dictionary|dictionaries  Operationen für Wörterbücher
+    configuration|config     Konfigurationsoperationen
+    help [command]           zeigt die Hilfe für den Befehl an
+```
+
+2. **Installieren Sie das Paket intlayer-cli global**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Es sollte nicht notwendig sein, wenn Sie das `intlayer`-Paket bereits installiert haben
+
+3. **Installieren Sie das Paket global**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Starten Sie Ihr Terminal neu**  
+   Manchmal ist ein Neustart des Terminals erforderlich, damit neue Befehle erkannt werden.
+
+5. **Bereinigen und neu installieren**  
+   Wenn die oben genannten Lösungen nicht funktionieren:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Überprüfen Sie die Installationsdateien**  
+   Wenn das Problem weiterhin besteht, prüfen Sie, ob diese Dateien vorhanden sind:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (sollte ein `bin`-Feld mit Verweis auf `./dist/cjs/cli.cjs` enthalten)
+
+7. **Überprüfen Sie die PATH-Umgebungsvariable**  
+   Stellen Sie sicher, dass das globale npm-Bin-Verzeichnis in Ihrem PATH enthalten ist:
+
+```bash
+# Für Unix-basierte Systeme (macOS/Linux)
+echo $PATH
+# Sollte etwas wie /usr/local/bin oder ~/.npm-global/bin enthalten
+
+# Für Windows
+echo %PATH%
+# Sollte das npm globale Bin-Verzeichnis enthalten
+```
+
+8. **Verwenden Sie npx mit vollem Pfad**  
+   Wenn der Befehl immer noch nicht gefunden wird, versuchen Sie npx mit dem vollständigen Pfad zu verwenden:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Überprüfen Sie auf Konflikte bei Installationen**
+
+```bash
+# Liste aller global installierten Pakete
+npm list -g --depth=0
+
+# Entfernen Sie alle konfliktierenden globalen Installationen
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Dann neu installieren
+npm install -g intlayer
+```
+
+10. **Überprüfen Sie die Node.js- und npm-Versionen**  
+    Stellen Sie sicher, dass Sie kompatible Versionen verwenden:
+
+```bash
+node --version
+npm --version
+```
+
+    Wenn Sie eine veraltete Version verwenden, sollten Sie ein Update von Node.js und npm in Betracht ziehen.
+
+11. **Überprüfen Sie Berechtigungsprobleme**  
+    Wenn Sie Berechtigungsfehler erhalten:
+
+    ```bash
+    # Für Unix-basierte Systeme
+    sudo npm install -g intlayer
+
+    # Oder ändern Sie das Standardverzeichnis von npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Fügen Sie dies zu Ihrer ~/.profile oder ~/.bashrc hinzu:
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/de/locale_incorect_in_url.md

@@ -0,0 +1,86 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Falsche Locale aus URL abgerufen
+description: Erfahren Sie, wie Sie die falsche Locale, die aus der URL abgerufen wird, beheben können.
+keywords:
+  - locale
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - konfiguration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-falsch-in-url
+---
+
+# Falsche Locale aus URL abgerufen
+
+## Problembeschreibung
+
+Beim Versuch, den Locale-Parameter aus der URL abzurufen, kann es vorkommen, dass der Locale-Wert falsch ist:
+
+```js
+const { locale } = await params;
+console.log(locale); // gibt "about" zurück anstelle der erwarteten Locale
+```
+
+## Lösung
+
+### 1. Überprüfen Sie die Dateistruktur
+
+Stellen Sie sicher, dass Ihr Next.js App-Router-Pfad dieser Struktur folgt:
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Überprüfen Sie die Middleware-Konfiguration
+
+Das Problem tritt häufig auf, wenn die Middleware nicht vorhanden ist oder nicht ausgelöst wird. Die Middleware-Datei sollte sich befinden unter:
+
+```bash
+src/middleware.ts
+```
+
+Diese Middleware ist verantwortlich für das Umschreiben von Routen, wenn `prefixDefault` auf `false` gesetzt ist. Zum Beispiel schreibt sie `/en/about` in `/about` um.
+
+### 3. URL-Muster basierend auf der Konfiguration
+
+#### Standardkonfiguration (`prefixDefault: false`, `noPrefix: false`)
+
+- Englisch: `/about`
+- Französisch: `/fr/about`
+- Spanisch: `/es/about`
+
+#### Mit `prefixDefault: true`
+
+- Englisch: `/en/about`
+- Französisch: `/fr/about`
+- Spanisch: `/es/about`
+
+#### Mit `noPrefix: true`
+
+- Englisch: `/about`
+- Französisch: `/about`
+- Spanisch: `/about`
+
+src/app/[locale]/about/page.tsx
+
+```
+- Spanisch: `/es/about`
+
+#### Mit `noPrefix: true`
+
+- Englisch: `/about`
+- Französisch: `/about`
+- Spanisch: `/about`
+
+Für weitere Details zu diesen Konfigurationsoptionen siehe die [Konfigurationsdokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md).
+```

package/frequent_questions/de/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Statisches vs. dynamisches Rendering mit i18n in Next.js
+description: Erfahren Sie, wie Sie statisches vs. dynamisches Rendering mit i18n in Next.js verwenden.
+keywords:
+  - statisch
+  - dynamisch
+  - rendering
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - framework
+  - middleware
+  - konfiguration
+slugs:
+  - doc
+  - faq
+  - statisches-rendering
+---
+
+# Statisches vs. dynamisches Rendering mit i18n in Next.js
+
+## Das Problem mit **next-intl**
+
+- **Was passiert?**
+  Wenn Sie `useTranslations`, `getTranslations` oder einen anderen next-intl-Helfer _innerhalb einer Server-Komponente_ in einer i18n-gerouteten App (`/en/…`, `/fr/…`) verwenden, markiert Next.js die gesamte Route als **dynamisch**. ([Next Intl][1])
+
+- **Warum?**
+  next-intl liest die aktuelle Locale aus einem nur bei der Anfrage verfügbaren Header (`x-next-intl-locale`) über `headers()` aus. Da `headers()` eine **dynamische API** ist, verliert jede Komponente, die darauf zugreift, die statische Optimierung. ([Next Intl][1], [Next.js][2])
+
+- **Offizieller Workaround (Boilerplate)**
+
+  1. Exportieren Sie `generateStaticParams` mit jeder unterstützten Locale.
+  2. Rufen Sie `setRequestLocale(locale)` in **jedem** Layout/Seite _vor_ dem Aufruf von `useTranslations` auf. ([Next Intl][1])
+     Dies entfernt die Abhängigkeit vom Header, aber Sie haben nun zusätzlichen Code zu pflegen und eine instabile API in der Produktion.
+
+## Wie **intlayer** das Problem umgeht
+
+**Designentscheidungen**
+
+1. **Nur Routen-Parameter** – Die Locale stammt aus dem `[locale]` URL-Segment, das Next.js bereits an jede Seite übergibt.
+2. **Kompilierungszeit-Bundles** – Übersetzungen werden als reguläre ES-Module importiert, sodass sie baumgeschüttelt und zur Build-Zeit eingebettet werden.
+3. **Keine dynamischen APIs** – `useT()` liest aus dem React-Kontext, nicht aus `headers()` oder `cookies()`.
+4. **Keine zusätzliche Konfiguration** – Sobald Ihre Seiten unter `app/[locale]/` liegen, rendert Next.js automatisch eine HTML-Datei pro Locale vor.

package/frequent_questions/de/translated_path_url.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Kann ich den URL-Pfad übersetzen?
+description: Erfahren Sie, wie Sie den URL-Pfad übersetzen können.
+keywords:
+  - array
+  - inhalt
+  - deklaration
+  - intlayer
+  - middleware
+  - proxy
+  - umschreiben
+  - prefix
+  - locale
+  - url
+slugs:
+  - doc
+  - faq
+  - übersetzter-pfad-url
+---
+
+# Ist es möglich, URLs wie folgt zu übersetzen:
+
+```bash
+en -> /product (kein Präfix) oder /en/product (mit Präfix)
+fr -> /fr/produit
+es -> /es/producto
+```
+
+Intlayer erlaubt es leider nicht, die URLs wie angegeben zu übersetzen. Um dies zu erreichen, sollten Sie Ihre eigene Middleware oder einen Proxy verwenden, um die URLs umzuschreiben.
+
+Sie können jedoch die Funktion `getMultilingualUrl` verwenden, um das Präfix für eine bestimmte Locale in die URL einzufügen.
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product (kein Präfix) oder /en/product (mit Präfix)
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+Oder `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // /fr/product
+```

package/frequent_questions/de/unknown_command.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Unbekannter Befehl
+description: Erfahren Sie, wie Sie den Fehler "unbekannter Befehl" beheben können.
+keywords:
+  - unbekannt
+  - befehl
+  - fehler
+  - intlayer
+  - fill
+  - build
+  - verbose
+  - terminal
+  - neustart
+  - lokal
+slugs:
+  - doc
+  - faq
+  - unbekannter-befehl
+---
+
+# Fehler: unbekannter Befehl fill / build / etc.
+
+Wenn `npx intlayer fill --verbose` ausgibt:
+
+```
+error: unknown command 'fill'
+```
+
+aber Sie sicher sind, dass der Befehl `fill` _existieren sollte_, folgen Sie diesen Schritten zur Behebung:
+
+## 1. **Stellen Sie sicher, dass Sie die neueste Version verwenden**
+
+Führen Sie aus:
+
+```bash
+npx intlayer --version                  # aktuelle lokal installierte intlayer Version
+npx intlayer@latest --version           # aktuellste intlayer Version
+```
+
+Dies erzwingt, dass `npx` die neueste Version lädt. Versuchen Sie es dann erneut:
+
+```bash
+npx intlayer@latest build --verbose
+```
+
+## 2. **Überprüfen Sie, ob der Befehl registriert ist**
+
+Sie können dies prüfen mit:
+
+```bash
+npx intlayer --help                     # zeigt Informationen zu den Befehlen an
+```
+
+Sehen Sie nach, ob der Befehl in der Befehlsliste erscheint.
+
+Gehen Sie ins Repository und bestätigen Sie, dass Ihr Befehl exportiert und im CLI-Einstiegspunkt registriert ist. Intlayer verwendet `commander` als Framework.
+
+Code bezüglich der CLI:
+https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/cli/src/cli.ts
+
+## 4. **Starten Sie Ihr Terminal neu**
+
+Manchmal ist ein Neustart des Terminals erforderlich, damit neue Befehle erkannt werden.
+
+## 5. **Wenn Sie `intlayer` entwickeln, bauen Sie es neu und verlinken Sie es**
+
+Wenn Sie `intlayer` lokal entwickeln:
+
+```bash
+# Im intlayer-Verzeichnis
+npm install
+npm run build
+npm link
+```
+
+Dann in einem anderen Terminal:
+
+```bash
+intlayer fill --verbose
+```
+
+Dies verwendet die lokale Version, an der Sie gerade arbeiten.
+
+## 6. **Leeren Sie den npx-Cache (falls Sie mit einer älteren Version festhängen)**
+
+```bash
+npx clear-npx-cache
+```
+
+Oder löschen Sie manuell zwischengespeicherte intlayer-Pakete:
+
+```bash
+rm -rf ~/.npm/_npx
+```
+
+Überprüfen Sie das Äquivalent, wenn Sie pnpm, yarn, bun oder einen anderen Paketmanager verwenden.

package/frequent_questions/en/SSR_Next_no_[locale].md

@@ -0,0 +1,105 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Is it possible to use Intlayer with Next.js without `[locale]` in the page path?
+description: Learn how to use Intlayer with Next.js without `[locale]` in the page path.
+keywords:
+  - locale
+  - path
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - ssr-next-no-[locale]
+---
+
+# Is it possible to use Intlayer with Next.js without `[locale]` in the page path?
+
+Yes, it's possible to use Intlayer with Next.js without `[locale]` in the page path. However, it is not recommended to do, because splitting you page page allows to trigger more keyswords on search engines. Your SSR may also be impacted.
+
+If you want to do it, follow the same steps as described in the [Intlayer with Next.js](https://intlayer.org/doc/environment/nextjs) guide,
+
+- no `src/middleware.ts`
+- no `generateStaticParams`
+
+```tsx fileName="src/app/layout.tsx"
+import type { FC, PropsWithChildren } from "react";
+
+const LocaleLayout: FC<PropsWithChildren> = ({ children }) => (
+  <html lang={undefined} dir={undefined}>
+    <body className={inter.className}>{children}</body>
+  </html>
+);
+
+export default LocaleLayout;
+```
+
+```tsx fileName="src/app/page.tsx"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { PageContent } from "@components/pageContent";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC = () => {
+  return (
+    <IntlayerServerProvider>
+      <PageContent />
+      <ServerComponentExample />
+
+      <IntlayerClientProvider>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```tsx fileName="src/component/pageContent.ts"
+"use client";
+
+import { type FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { useHTMLLanguage } from "@hooks/htmlTextDir";
+
+const PageContent: FC = () => {
+  useHTMLLanguage();
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/hooks/htmlTextDir.ts"
+"use client";
+
+import { useEffect } from "react";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const useHTMLLanguage = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    if (!document) return;
+
+    document.documentElement.lang = locale;
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```