@intlayer/docs 5.5.8

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

@@ -0,0 +1,266 @@
+# next-intlayer : Paquet NPM pour internationaliser (i18n) une application Next.js
+
+**Intlayer** est une suite de paquets conçue spécifiquement pour les développeurs JavaScript. Elle est compatible avec des frameworks comme React, Next.js et Express.js.
+
+**Le paquet `next-intlayer`** vous permet d'internationaliser votre application Next.js. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation de Next.js. De plus, il inclut le plugin Next.js pour intégrer Intlayer avec [Webpack](https://webpack.js.org/) ou [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), ainsi qu'un middleware pour détecter la langue préférée de l'utilisateur, gérer les cookies et gérer la redirection des URL.
+
+## Pourquoi internationaliser votre application Next.js ?
+
+Internationaliser votre application Next.js 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 propulsée par JavaScript** : Exploitez la flexibilité de JavaScript pour définir et gérer efficacement votre contenu.
+- **Environnement sûr pour les types** : 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 paquet nécessaire en utilisant votre gestionnaire de paquets préféré :
+
+```bash packageManager="npm"
+npm install next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add next-intlayer
+```
+
+## Exemple d'utilisation
+
+Avec Intlayer, vous pouvez déclarer votre contenu de manière structurée n'importe où dans votre base de 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
+        ├── ClientComponent
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── ServerComponent
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── ServerComponent
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── ServerComponent
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Déclarez votre contenu
+
+`next-intlayer` est conçu pour fonctionner avec le [paquet `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/intlayer/index.md). `intlayer` est un paquet 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 dans votre application.
+
+Voici un exemple de déclaration de contenu :
+
+```tsx fileName="src/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+// Déclaration de contenu pour le composant client
+const clientComponentContent = {
+  key: "client-component",
+  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 clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+// Déclaration de contenu pour le composant client
+const clientComponentContent = {
+  key: "client-component",
+  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 clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+// Déclaration de contenu pour le composant client
+const clientComponentContent = {
+  key: "client-component",
+  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 = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "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/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Créez une déclaration de contenu associée
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Maîtriser l'internationalisation de votre application Next.js
+
+Intlayer offre de nombreuses fonctionnalités pour vous aider à internationaliser votre application Next.js. Voici quelques-unes des principales fonctionnalités :
+
+- **Internationalisation des composants serveur** : Intlayer vous permet d'internationaliser vos composants serveur de la même manière que vos composants client. Cela signifie que vous pouvez utiliser les mêmes déclarations de contenu pour les composants client et serveur.
+- **Middleware pour la détection de la langue** : Intlayer fournit un middleware pour détecter la langue préférée de l'utilisateur. Ce middleware est utilisé pour détecter la langue préférée de l'utilisateur et les rediriger vers l'URL appropriée comme spécifié dans la [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/fr/configuration.md).
+- **Internationalisation des métadonnées** : Intlayer fournit un moyen d'internationaliser vos métadonnées, comme le titre de votre page, en utilisant la fonction `generateMetadata` fournie par Next.js. Vous pouvez utiliser la fonction `getTranslation` pour traduire vos métadonnées.
+- **Internationalisation des fichiers sitemap.xml et robots.txt** : Intlayer vous permet d'internationaliser vos fichiers sitemap.xml et robots.txt. Vous pouvez utiliser la fonction `getMultilingualUrls` pour générer des URL multilingues pour votre sitemap.
+- **Internationalisation des URL** : Intlayer vous permet d'internationaliser vos URL en utilisant la fonction `getMultilingualUrls`. Cette fonction génère des URL multilingues pour votre sitemap.
+
+**Pour en savoir plus sur ces fonctionnalités, consultez le guide [Internationalisation (i18n) de Next.js avec Intlayer et le routeur d'application Next.js 15](https://github.com/aymericzip/intlayer/blob/main/docs/fr/intlayer_with_nextjs_15.md).**
+
+## Fonctions fournies par le paquet `next-intlayer`
+
+Le paquet `next-intlayer` fournit également des fonctions pour vous aider à internationaliser votre application.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/next-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/next-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/next-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/next-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/fr/packages/next-intlayer/useIntlayerAsync.md)

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

@@ -0,0 +1,325 @@
+# Documentation: Fonction `t` dans `next-intlayer`
+
+La fonction `t` dans le package `next-intlayer` est un outil fondamental pour l'internationalisation en ligne dans votre application Next.js. 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 des traductions pour chaque langue prise en charge, `t` retourne la traduction appropriée en fonction du contexte de langue actuel dans votre application Next.js.
+
+---
+
+## Principales fonctionnalité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 de TypeScript** : Offre une sécurité de type et une autocomplétion lorsqu'elle est utilisée avec TypeScript.
+- **Intégration facile** : Fonctionne parfaitement dans les composants client et serveur de Next.js.
+
+---
+
+## 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 des 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 de `t` dans un composant client
+
+Assurez-vous d'inclure la directive `'use client';` en haut de votre fichier de composant lorsque vous utilisez `t` dans un composant côté client.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un exemple de composant client",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un exemple de composant client",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es le contenido d un exemple de composant client",
+    })}
+  </p>
+);
+```
+
+### Utilisation de `t` dans un composant serveur
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenu de un exemple de composant serveur",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es le contenu de un exemple de composant serveur",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es le contenu de un exemple de composant serveur",
+    })}
+  </p>
+);
+```
+
+### 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 avec TypeScript
+
+La fonction `t` est sûre en termes de types lorsqu'elle est utilisée avec TypeScript, garantissant que toutes les langues requises sont fournies.
+
+```typescript codeFormat="typescript"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### Détection de la langue et contexte
+
+Dans `next-intlayer`, la langue actuelle est gérée via des fournisseurs de contexte : `IntlayerClientProvider` et `IntlayerServerProvider`. Assurez-vous que ces fournisseurs enveloppent vos composants et que la propriété `locale` est correctement passée.
+
+#### Exemple :
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Vos composants ici */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Vos composants ici */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Vos composants ici */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## 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 `IntlayerClientProvider` ou le `IntlayerServerProvider` 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, ce qui entraîne 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 [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // L'absence de 'es' entraînera une erreur TypeScript [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // L'absence de 'es' entraînera une erreur TypeScript [!code error]
+};
+
+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 votre application via les fournisseurs appropriés.
+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 `next-intlayer` est un outil puissant et pratique pour gérer les traductions en ligne dans vos applications Next.js. 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 next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/fr/intlayer_visual_editor.md).
+
+---
+
+**Remarque** : N'oubliez pas de configurer correctement vos `IntlayerClientProvider` et `IntlayerServerProvider` pour garantir que la langue actuelle est correctement transmise à vos composants. Cela est crucial pour que la fonction `t` retourne les bonnes traductions.