@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/es/testing.md

@@ -0,0 +1,200 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: Probando tu contenido
+description: Descubre cómo probar tu contenido con Intlayer.
+keywords:
+  - Pruebas
+  - Intlayer
+  - Internacionalización
+  - CMS
+  - Sistema de Gestión de Contenidos
+  - Editor Visual
+slugs:
+  - doc
+  - testing
+---
+
+# Probando tu contenido
+
+Esta guía muestra cómo verificar automáticamente que tus diccionarios estén completos, detectar traducciones faltantes antes de lanzar y probar la interfaz localizada en tu aplicación.
+
+---
+
+## Qué puedes probar
+
+- **Traducciones faltantes**: falla en CI si faltan locales requeridos en cualquier diccionario.
+- **Renderizado de UI localizada**: renderiza componentes con un proveedor de locales específico y verifica el texto/atributos visibles.
+- **Auditorías en tiempo de compilación**: ejecuta una auditoría rápida localmente vía CLI.
+
+---
+
+## Inicio rápido: auditoría vía CLI
+
+Ejecuta la auditoría desde la raíz de tu proyecto:
+
+```bash
+npx intlayer content test
+```
+
+Flags útiles:
+
+- `--env-file [ruta]`: carga variables de entorno desde un archivo.
+- `-e, --env [nombre]`: selecciona un perfil de entorno.
+- `--base-dir [ruta]`: establece el directorio base de la aplicación para la resolución.
+- `--verbose`: muestra registros detallados.
+- `--prefix [etiqueta]`: prefija las líneas de registro.
+
+Nota: la CLI imprime un informe detallado pero no termina con un código distinto de cero en caso de fallos. Para control en CI, añade una prueba unitaria (más abajo) que verifique que no hay locales requeridos faltantes.
+
+---
+
+## Prueba programática (Vitest/Jest)
+
+Usa la API CLI de Intlayer para asegurar que no falten traducciones en tus locales requeridos.
+
+```ts fileName=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("traducciones", () => {
+  it("no tiene locales requeridos faltantes", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // Útil cuando la prueba falla localmente o en CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Equivalente en Jest:
+
+```ts fileName=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("no tiene locales requeridos faltantes", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+Cómo funciona:
+
+- Intlayer lee tu configuración (locales, requiredLocales) y los diccionarios declarados, luego informa:
+  - `missingTranslations`: por clave, qué locales faltan y de qué archivo.
+  - `missingLocales`: unión de todos los locales faltantes.
+  - `missingRequiredLocales`: subconjunto limitado a `requiredLocales` (o todos los locales si `requiredLocales` no está definido).
+
+---
+
+## Pruebas de UI localizada (React / Next.js)
+
+Renderiza componentes bajo un proveedor de Intlayer y verifica el contenido visible.
+
+Ejemplo en React (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localized title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByText("Título esperado en inglés")).toBeInTheDocument();
+});
+```
+
+Ejemplo en Next.js (App Router): usa el envoltorio del framework:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("renderiza encabezado localizado en francés", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+Consejos:
+
+- Cuando necesites valores de cadena sin procesar para atributos (por ejemplo, `aria-label`), accede al campo `.value` que devuelve `useIntlayer` en React.
+- Mantén los diccionarios junto con los componentes para facilitar las pruebas unitarias y la limpieza.
+
+---
+
+## Integración Continua
+
+Agrega una prueba que falle la compilación cuando falten traducciones requeridas.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+Ejemplo de GitHub Actions:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+Opcional: ejecuta la auditoría CLI para un resumen legible por humanos junto con las pruebas:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## Solución de Problemas
+
+- Asegúrate de que tu configuración de Intlayer defina `locales` y (opcionalmente) `requiredLocales`.
+- Si tu aplicación usa diccionarios dinámicos o remotos, ejecuta las pruebas en un entorno donde los diccionarios estén disponibles.
+- Para monorepos mixtos, usa `--base-dir` para apuntar la CLI a la raíz correcta de la aplicación.
+
+---
+
+## Historial de la Documentación
+
+| Versión | Fecha      | Cambios                 |
+| ------- | ---------- | ----------------------- |
+| 6.0.0   | 2025-09-20 | Introducción de pruebas |

package/docs/fr/autoFill.md

@@ -1,12 +1,12 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
-title: Remplissage Automatique
-description: Apprenez à utiliser la fonctionnalité de remplissage automatique dans Intlayer pour peupler automatiquement le contenu basé sur des modèles prédéfinis. Suivez cette documentation pour implémenter efficacement les fonctionnalités de remplissage automatique dans votre projet.
+updatedAt: 2025-09-20
+title: Remplissage automatique
+description: Apprenez à utiliser la fonctionnalité de remplissage automatique dans Intlayer pour remplir automatiquement le contenu en fonction de modèles prédéfinis. Suivez cette documentation pour implémenter efficacement les fonctionnalités de remplissage automatique dans votre projet.
 keywords:
-  - Remplissage Automatique
-  - Automatisation de Contenu
-  - Contenu Dynamique
+  - Remplissage automatique
+  - Automatisation du contenu
+  - Contenu dynamique
   - Intlayer
   - Next.js
   - JavaScript
@@ -17,10 +17,11 @@ slugs:
   - auto-fill
 ---
 
-# Traductions des Fichiers de Déclaration de Contenu avec Remplissage Automatique
+# Traductions des fichiers de déclaration de contenu avec remplissage automatique
 
-**Les fichiers de déclaration de contenu avec remplissage automatique** sont un moyen d'accélérer votre flux de développement.
-Le mécanisme de remplissage automatique fonctionne par une relation _maître-esclave_ entre les fichiers de déclaration de contenu. Lorsque le fichier principal (maître) est mis à jour, Intlayer applique automatiquement ces modifications aux fichiers de déclaration dérivés (remplis automatiquement).
+**Les fichiers de déclaration de contenu avec remplissage automatique** sont un moyen d'accélérer votre flux de travail de développement.
+
+Le mécanisme de remplissage automatique fonctionne via une relation _maître-esclave_ entre les fichiers de déclaration de contenu. Lorsque le fichier principal (maître) est mis à jour, Intlayer applique automatiquement ces modifications aux fichiers de déclaration dérivés (remplis automatiquement).
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -30,14 +31,14 @@ const exampleContent = {
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "Ceci est un exemple de contenu",
+    contentExample: "Ceci est un exemple de contenu", // Exemple de contenu
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-Voici un [fichier de déclaration de contenu par locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/per_locale_file.md) utilisant l'instruction `autoFill`.
+Voici un [fichier de déclaration de contenu par langue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/per_locale_file.md) utilisant l'instruction `autoFill`.
 
 Ensuite, lorsque vous exécutez la commande suivante :
 
@@ -45,7 +46,7 @@ Ensuite, lorsque vous exécutez la commande suivante :
 npx intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer générera automatiquement le fichier de déclaration dérivé à `src/components/example/example.content.json`, remplissant toutes les locales non encore déclarées dans le fichier principal.
+Intlayer générera automatiquement le fichier de déclaration dérivé à `src/components/example/example.content.json`, en remplissant toutes les locales non déjà déclarées dans le fichier principal.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -64,9 +65,9 @@ Intlayer générera automatiquement le fichier de déclaration dérivé à `src/
 
 Ensuite, les deux fichiers de déclaration seront fusionnés en un seul dictionnaire, accessible via le hook standard `useIntlayer("example")` (react) / composable (vue).
 
-## Format du fichier autofill
+## Format du fichier rempli automatiquement
 
-Le format recommandé pour les fichiers de déclaration autofillés est **JSON**, ce qui permet d'éviter les contraintes de formatage. Cependant, Intlayer supporte également les formats `.ts`, `.js`, `.mjs`, `.cjs` et autres.
+Le format recommandé pour les fichiers de déclaration remplis automatiquement est **JSON**, ce qui permet d'éviter les contraintes de formatage. Cependant, Intlayer prend également en charge les formats `.ts`, `.js`, `.mjs`, `.cjs` et d'autres.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -78,7 +79,7 @@ const exampleContent = {
 };
 ```
 
-Cela générera le fichier à l'emplacement :
+Cela générera le fichier à l'emplacement suivant :
 
 ```
 src/components/example/example.filled.content.ts
@@ -103,13 +104,13 @@ const exampleContent = {
 };
 ```
 
-Cela générera le fichier à l'emplacement suivant :
+Cela générera le fichier à l'emplacement :
 
 ```
 /messages/example.content.json
 ```
 
-## Génération Automatique des Fichiers de Déclaration de Contenu Par Locale
+## Génération Automatique de Fichiers de Déclaration de Contenu Par Locale
 
 Le champ `autoFill` supporte également la génération de fichiers de déclaration de contenu **par locale**.
 
@@ -126,14 +127,16 @@ const exampleContent = {
 };
 ```
 
-Cela générera deux fichiers distincts :
+Cela générera deux fichiers séparés :
 
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## Filtrer l'auto-remplissage pour une locale spécifique
+> Dans ce cas, si l'objet ne contient pas toutes les locales, Intlayer ignore la génération des locales restantes.
 
-Utiliser un objet pour le champ `autoFill` vous permet d'appliquer des filtres et de générer uniquement les fichiers pour des locales spécifiques.
+## Filtrer le remplissage automatique pour une locale spécifique
+
+Utiliser un objet pour le champ `autoFill` vous permet d'appliquer des filtres et de générer uniquement certains fichiers de locale.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -147,18 +150,19 @@ const exampleContent = {
 };
 ```
 
-Cela générera uniquement le fichier de traduction français.
+Cela ne générera que le fichier de traduction français.
 
 ## Variables de chemin
 
-Vous pouvez utiliser des variables dans le chemin `autoFill` pour résoudre dynamiquement les chemins cibles des fichiers générés.
+ Vous pouvez utiliser des variables dans le chemin `autoFill` pour résoudre dynamiquement les chemins cibles des fichiers générés.
 
 **Variables disponibles :**
 
 - `{{locale}}` – Code de la locale (ex. `fr`, `es`)
+- `{{fileName}}` – Nom du fichier (ex. `index`)
 - `{{key}}` – Clé du dictionnaire (ex. `example`)
 
-```ts fileName="src/components/example/example.content.ts"
+```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
   autoFill: "/messages/{{locale}}/{{key}}.content.json",
@@ -173,6 +177,25 @@ Cela générera :
 - `/messages/fr/example.content.json`
 - `/messages/es/example.content.json`
 
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // Votre contenu
+  },
+};
+```
+
+Cela générera :
+
+- `./index.content.json`
+- `./index.content.json`
+
 ## Historique de la documentation
 
-- 5.5.10 - 2025-06-29 : Historique initial
+| Version | Date       | Modifications               |
+| ------- | ---------- | --------------------------- |
+| 6.0.0   | 2025-09-20 | Ajout de la configuration globale |
+| 6.0.0   | 2025-09-17 | Ajout de la variable `{{fileName}}` |
+| 5.5.10  | 2025-06-29 | Historique initial          |