@intlayer/docs 5.5.8

package/fr/packages/next-intlayer/useLocale.md

@@ -0,0 +1,105 @@
+# Intégration Next.js : Documentation du Hook `useLocale` pour `next-intlayer`
+
+Cette section offre une documentation détaillée sur le hook `useLocale` conçu pour les applications Next.js dans la bibliothèque `next-intlayer`. Il est conçu pour gérer efficacement les changements de langue et le routage.
+
+## Importer `useLocale` dans Next.js
+
+Pour utiliser le hook `useLocale` dans votre application Next.js, importez-le comme suit :
+
+```javascript
+import { useLocale } from "next-intlayer"; // Utilisé pour gérer les langues et le routage dans Next.js
+```
+
+## Utilisation
+
+Voici comment implémenter le hook `useLocale` dans un composant Next.js :
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Langue actuelle : {locale}</h1>
+      <p>Langue par défaut : {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Langue actuelle : {locale}</h1>
+      <p>Langue par défaut : {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Langue actuelle : {locale}</h1>
+      <p>Langue par défaut : {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+## Paramètres et Valeurs de Retour
+
+Lorsque vous invoquez le hook `useLocale`, il retourne un objet contenant les propriétés suivantes :
+
+- **`locale`** : La langue actuelle définie dans le contexte React.
+- **`defaultLocale`** : La langue principale définie dans la configuration.
+- **`availableLocales`** : Une liste de toutes les langues disponibles définies dans la configuration.
+- **`setLocale`** : Une fonction pour changer la langue de l'application et mettre à jour l'URL en conséquence. Elle gère les règles de préfixe, qu'il s'agisse d'ajouter ou non la langue au chemin en fonction de la configuration. Utilise `useRouter` de `next/navigation` pour les fonctions de navigation comme `push` et `refresh`.
+- **`pathWithoutLocale`** : Une propriété calculée qui retourne le chemin sans la langue. Elle est utile pour comparer les URLs. Par exemple, si la langue actuelle est `fr`, et l'url `fr/my_path`, le chemin sans langue est `/my_path`. Utilise `usePathname` de `next/navigation` pour obtenir le chemin actuel.
+
+## Conclusion
+
+Le hook `useLocale` de `next-intlayer` est un outil essentiel pour gérer les langues dans les applications Next.js. Il offre une approche intégrée pour adapter votre application à plusieurs langues en gérant le stockage des langues, la gestion des états et les modifications d'URL de manière transparente.

package/fr/packages/preact-intlayer/index.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/preact-intlayer/index.md

package/fr/packages/react-intlayer/index.md

@@ -0,0 +1,257 @@
+# react-intlayer : Package NPM pour internationaliser (i18n) une application React
+
+**Intlayer** est une suite de packages conçue spécifiquement pour les développeurs JavaScript. Elle est compatible avec des frameworks comme React, React et Express.js.
+
+**Le package `react-intlayer`** vous permet d'internationaliser votre application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation dans React.
+
+## Pourquoi internationaliser votre application React ?
+
+Internationaliser votre application React est essentiel pour servir efficacement un public mondial. Cela permet à votre application de fournir du contenu et des messages dans la langue préférée de chaque utilisateur. Cette capacité améliore l'expérience utilisateur et élargit la portée de votre application en la rendant plus accessible et pertinente pour des personnes de différents horizons linguistiques.
+
+## Pourquoi intégrer Intlayer ?
+
+- **Gestion de contenu alimentée par JavaScript** : Exploitez la flexibilité de JavaScript pour définir et gérer efficacement votre contenu.
+- **Environnement Type-Safe** : Utilisez TypeScript pour garantir que toutes vos définitions de contenu sont précises et sans erreur.
+- **Fichiers de contenu intégrés** : Gardez vos traductions proches de leurs composants respectifs, améliorant ainsi la maintenabilité et la clarté.
+
+## Installation
+
+Installez le package nécessaire en utilisant votre gestionnaire de packages préféré :
+
+```bash packageManager="npm"
+npm install react-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-intlayer
+```
+
+## Exemple d'utilisation
+
+Avec Intlayer, vous pouvez déclarer votre contenu de manière structurée n'importe où dans votre code.
+
+Par défaut, Intlayer recherche les fichiers avec l'extension `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> Vous pouvez modifier l'extension par défaut en définissant la propriété `contentDir` dans le [fichier de configuration](https://github.com/aymericzip/intlayer/blob/main/docs/fr/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── Component2
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── Component2
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── Component2
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Déclarez votre contenu
+
+`react-intlayer` est conçu pour fonctionner avec le package [`intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/intlayer/index.md). `intlayer` est un package qui vous permet de déclarer votre contenu n'importe où dans votre code. Il convertit les déclarations de contenu multilingues en dictionnaires structurés qui s'intègrent parfaitement à votre application.
+
+Voici un exemple de déclaration de contenu :
+
+```tsx fileName="src/Component1/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Moins d'une voiture",
+      "-1": "Moins une voiture",
+      "0": "Aucune voiture",
+      "1": "Une voiture",
+      ">5": "Quelques voitures",
+      ">19": "Beaucoup de voitures",
+    }),
+  },
+} satisfies Dictionary;
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Moins d'une voiture",
+      "-1": "Moins une voiture",
+      "0": "Aucune voiture",
+      "1": "Une voiture",
+      ">5": "Quelques voitures",
+      ">19": "Beaucoup de voitures",
+    }),
+  },
+};
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Moins d'une voiture",
+      "-1": "Moins une voiture",
+      "0": "Aucune voiture",
+      "1": "Une voiture",
+      ">5": "Quelques voitures",
+      ">19": "Beaucoup de voitures",
+    }),
+  },
+};
+
+module.exports = component1Content;
+```
+
+```json fileName="src/Component1/index.content.json" codeFormat="json"
+{
+  "key": "component-1",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Moins d'une voiture",
+        "-1": "Moins une voiture",
+        "0": "Aucune voiture",
+        "1": "Une voiture",
+        ">5": "Quelques voitures",
+        ">19": "Beaucoup de voitures"
+      }
+    }
+  }
+}
+```
+
+### Utilisez le contenu dans votre code
+
+Une fois que vous avez déclaré votre contenu, vous pouvez l'utiliser dans votre code. Voici un exemple d'utilisation du contenu dans un composant React :
+
+```tsx {4,7} fileName="src/components/Component1Example.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const Component1Example: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "react-intlayer";
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("react-intlayer");
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Maîtriser l'internationalisation de votre application React
+
+Intlayer offre de nombreuses fonctionnalités pour vous aider à internationaliser votre application React.
+
+**Pour en savoir plus sur ces fonctionnalités, consultez le guide [Internationalisation (i18n) de React avec Intlayer et Vite et React](https://github.com/aymericzip/intlayer/blob/main/docs/fr/intlayer_with_vite+react.md) pour les applications Vite et React, ou le guide [Internationalisation (i18n) de React avec Intlayer et React (CRA)](https://github.com/aymericzip/intlayer/blob/main/docs/fr/intlayer_with_create_react_app.md) pour React Create App.**
+
+## Fonctions fournies par le package `react-intlayer`
+
+Le package `react-intlayer` fournit également des fonctions pour vous aider à internationaliser votre application.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/react-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/react-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/react-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/react-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/react-intlayer/useIntlayerAsync.md)

package/fr/packages/react-intlayer/t.md

@@ -0,0 +1,277 @@
+# Documentation: Fonction `t` dans `react-intlayer`
+
+La fonction `t` dans le package `react-intlayer` est un outil fondamental pour l'internationalisation en ligne dans votre application React. Elle vous permet de définir des traductions directement dans vos composants, ce qui simplifie l'affichage de contenu localisé en fonction de la langue actuelle.
+
+---
+
+## Vue d'ensemble
+
+La fonction `t` est utilisée pour fournir des traductions pour différentes langues directement dans vos composants. En passant un objet contenant les traductions pour chaque langue prise en charge, `t` retourne la traduction appropriée en fonction du contexte de langue actuel dans votre application React.
+
+---
+
+## Fonctionnalités clés
+
+- **Traductions en ligne** : Idéal pour des textes rapides en ligne qui ne nécessitent pas de déclaration de contenu séparée.
+- **Sélection automatique de la langue** : Retourne automatiquement la traduction correspondant à la langue actuelle.
+- **Support TypeScript** : Offre une sécurité de type et une autocomplétion lorsqu'il est utilisé avec TypeScript.
+- **Intégration facile** : Fonctionne parfaitement dans les composants React.
+
+---
+
+## Signature de la fonction
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Paramètres
+
+- `translations` : Un objet où les clés sont les codes de langue (par exemple, `en`, `fr`, `es`) et les valeurs sont les chaînes traduites correspondantes.
+
+### Retourne
+
+- Une chaîne représentant le contenu traduit pour la langue actuelle.
+
+---
+
+## Exemples d'utilisation
+
+### Utilisation basique de `t` dans un composant
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { t } from "react-intlayer";
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { t } = require("react-intlayer");
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un exemple de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+### Traductions en ligne dans les attributs
+
+La fonction `t` est particulièrement utile pour les traductions en ligne dans les attributs JSX. Lors de la localisation d'attributs comme `alt`, `title`, `href` ou `aria-label`, vous pouvez utiliser `t` directement dans l'attribut.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+    })}
+  />
+</button>
+```
+
+---
+
+## Sujets avancés
+
+### Intégration TypeScript
+
+La fonction `t` est sécurisée par type lorsqu'elle est utilisée avec TypeScript, garantissant que toutes les langues requises sont fournies.
+
+```typescript codeFormat="typescript"
+import { t, type IConfigLocales } from "react-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import { t, type IConfigLocales } from "react-intlayer";
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### Détection et contexte de langue
+
+Dans `react-intlayer`, la langue actuelle est gérée via le `IntlayerProvider`. Assurez-vous que ce fournisseur enveloppe vos composants et que la propriété `locale` est correctement passée.
+
+#### Exemple :
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Vos composants ici */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { IntlayerProvider } from "react-intlayer";
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Vos composants ici */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Vos composants ici */}
+  </IntlayerProvider>
+);
+```
+
+---
+
+## Erreurs courantes et dépannage
+
+### `t` retourne une valeur indéfinie ou une traduction incorrecte
+
+- **Cause** : La langue actuelle n'est pas correctement définie ou la traduction pour la langue actuelle est manquante.
+- **Solution** :
+  - Vérifiez que le `IntlayerProvider` est correctement configuré avec la langue appropriée.
+  - Assurez-vous que votre objet de traductions inclut toutes les langues nécessaires.
+
+### Traductions manquantes dans TypeScript
+
+- **Cause** : L'objet de traductions ne satisfait pas les langues requises, entraînant des erreurs TypeScript.
+- **Solution** : Utilisez le type `IConfigLocales` pour garantir l'exhaustivité de vos traductions.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // L'absence de 'es' entraînera une erreur TypeScript
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // L'absence de 'es' entraînera une erreur TypeScript
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // L'absence de 'es' entraînera une erreur TypeScript
+};
+
+const text = t(translations);
+```
+
+---
+
+## Conseils pour une utilisation efficace
+
+1. **Utilisez `t` pour des traductions simples en ligne** : Idéal pour traduire de petits morceaux de texte directement dans vos composants.
+2. **Préférez `useIntlayer` pour un contenu structuré** : Pour des traductions plus complexes et une réutilisation du contenu, définissez le contenu dans des fichiers de déclaration et utilisez `useIntlayer`.
+3. **Fourniture cohérente de la langue** : Assurez-vous que votre langue est fournie de manière cohérente dans toute votre application via le `IntlayerProvider`.
+4. **Exploitez TypeScript** : Utilisez les types TypeScript pour détecter les traductions manquantes et garantir la sécurité des types.
+
+---
+
+## Conclusion
+
+La fonction `t` dans `react-intlayer` est un outil puissant et pratique pour gérer les traductions en ligne dans vos applications React. En l'intégrant efficacement, vous améliorez les capacités d'internationalisation de votre application, offrant une meilleure expérience aux utilisateurs du monde entier.
+
+Pour une utilisation plus détaillée et des fonctionnalités avancées, consultez la [documentation react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/fr/intlayer_visual_editor.md).
+
+---
+
+**Remarque** : N'oubliez pas de configurer correctement votre `IntlayerProvider` pour garantir que la langue actuelle est correctement transmise à vos composants. Cela est crucial pour que la fonction `t` retourne les traductions correctes.