@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/en-GB/testing.md

@@ -0,0 +1,200 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: Testing your content
+description: Discover how to test your content with Intlayer.
+keywords:
+  - Testing
+  - Intlayer
+  - Internationalisation
+  - CMS
+  - Content Management System
+  - Visual Editor
+slugs:
+  - doc
+  - testing
+---
+
+# Testing your content
+
+This guide shows how to automatically verify your dictionaries are complete, catch missing translations before shipping, and test localised UI in your app.
+
+---
+
+## What you can test
+
+- **Missing translations**: fail CI if any required locales are missing for any dictionary.
+- **Localised UI rendering**: render components with a specific locale provider and assert on visible text/attributes.
+- **Build-time audits**: run a quick audit locally via CLI.
+
+---
+
+## Quick start: audit via CLI
+
+Run the audit from your project root:
+
+```bash
+npx intlayer content test
+```
+
+Useful flags:
+
+- `--env-file [path]`: load environment variables from a file.
+- `-e, --env [name]`: select an environment profile.
+- `--base-dir [path]`: set the app base directory for resolution.
+- `--verbose`: show verbose logs.
+- `--prefix [label]`: prefix log lines.
+
+Note: the CLI prints a detailed report but does not exit with a non-zero code on failures. For CI gating, add a unit test (below) that asserts zero missing required locales.
+
+---
+
+## Programmatic test (Vitest/Jest)
+
+Use the Intlayer CLI API to assert there are no missing translations for your required locales.
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("has no missing required locales", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // Useful when the test fails locally or in CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Jest equivalent:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+How it works:
+
+- Intlayer reads your configuration (locales, requiredLocales) and declared dictionaries, then reports:
+  - `missingTranslations`: per‑key, which locales are missing and from which file.
+  - `missingLocales`: union of all missing locales.
+  - `missingRequiredLocales`: subset limited to `requiredLocales` (or all locales if `requiredLocales` is not set).
+
+---
+
+## Testing localised UI (React / Next.js)
+
+Render components under an Intlayer provider and assert on visible content.
+
+React example (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localised title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByText("Expected English title")).toBeInTheDocument();
+});
+```
+
+Next.js (App Router) example: use the framework wrapper:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("renders localised heading in French", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+Tips:
+
+- When you need raw string values for attributes (e.g., `aria-label`), access the `.value` field returned by `useIntlayer` in React.
+- Keep dictionaries colocated with components for easier unit testing and cleanup.
+
+---
+
+## Continuous Integration
+
+Add a test that fails the build when required translations are missing.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+GitHub Actions example:
+
+```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
+```
+
+Optional: run the CLI audit for a human-readable summary alongside tests:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## Troubleshooting
+
+- Ensure your Intlayer configuration defines `locales` and (optionally) `requiredLocales`.
+- If your app uses dynamic or remote dictionaries, run tests in an environment where the dictionaries are available.
+- For mixed monorepos, use `--base-dir` to point the CLI at the correct application root.
+
+---
+
+## Doc History
+
+| Version | Date       | Changes                 |
+| ------- | ---------- | ----------------------- |
+| 6.0.0   | 2025-09-20 | Introduction of testing |

package/docs/es/autoFill.md

@@ -1,10 +1,10 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
-title: Autocompletar
-description: Aprende cómo usar la funcionalidad de autocompletar en Intlayer para poblar automáticamente contenido basado en patrones predefinidos. Sigue esta documentación para implementar funciones de autocompletar de manera eficiente en tu proyecto.
+updatedAt: 2025-09-20
+title: Relleno Automático
+description: Aprende a usar la funcionalidad de relleno automático en Intlayer para poblar contenido automáticamente basado en patrones predefinidos. Sigue esta documentación para implementar funciones de relleno automático de manera eficiente en tu proyecto.
 keywords:
-  - Autocompletar
+  - Relleno Automático
   - Automatización de Contenido
   - Contenido Dinámico
   - Intlayer
@@ -17,28 +17,28 @@ slugs:
   - auto-fill
 ---
 
-# Archivos de Declaración de Contenido con Autocompletar
+# Traducciones de Archivos de Declaración de Contenido con Relleno Automático
 
-**Los archivos de declaración de contenido con autocompletar** son una forma de acelerar tu flujo de trabajo de desarrollo.
-El mecanismo de autocompletar funciona a través de una relación _maestro-esclavo_ entre los archivos de declaración de contenido. Cuando el archivo principal (maestro) se actualiza, Intlayer aplicará automáticamente esos cambios a los archivos de declaración derivados (autocompletados).
+**Los archivos de declaración de contenido con relleno automático** son una forma de acelerar tu flujo de trabajo de desarrollo.
+
+El mecanismo de relleno automático funciona mediante una relación _maestro-esclavo_ entre archivos de declaración de contenido. Cuando el archivo principal (maestro) se actualiza, Intlayer aplicará automáticamente esos cambios a los archivos de declaración derivados (rellenados automáticamente).
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
 
-// Contenido de ejemplo con autocompletar configurado
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "This is an example of content", // Este es un ejemplo de contenido
+    contentExample: "Este es un ejemplo de contenido",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-Aquí tienes un [archivo de declaración de contenido por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/per_locale_file.md) que utiliza la instrucción `autoFill`.
+Aquí hay un [archivo de declaración de contenido por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/per_locale_file.md) que usa la instrucción `autoFill`.
 
 Luego, cuando ejecutes el siguiente comando:
 
@@ -63,11 +63,11 @@ Intlayer generará automáticamente el archivo de declaración derivado en `src/
 }
 ```
 
-Después, ambos archivos de declaración se fusionarán en un solo diccionario, accesible usando el hook estándar `useIntlayer("example")` (react) / composable (vue).
+Después, ambos archivos de declaración se fusionarán en un único diccionario, accesible mediante el hook estándar `useIntlayer("example")` (react) / composable (vue).
 
-## Formato del Archivo Autocompletado
+## Formato del Archivo Rellenado Automáticamente
 
-El formato recomendado para los archivos de declaración autofillados es **JSON**, lo que ayuda a evitar restricciones de formato. Sin embargo, Intlayer también soporta formatos `.ts`, `.js`, `.mjs`, `.cjs` y otros.
+El formato recomendado para los archivos de declaración autocompletados es **JSON**, lo que ayuda a evitar restricciones de formato. Sin embargo, Intlayer también soporta `.ts`, `.js`, `.mjs`, `.cjs` y otros formatos.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -87,8 +87,8 @@ src/components/example/example.filled.content.ts
 
 > La generación de archivos `.js`, `.ts` y similares funciona de la siguiente manera:
 >
-> - Si el archivo ya existe, Intlayer lo analizará usando el AST (Árbol de Sintaxis Abstracta) para localizar cada campo e insertar las traducciones que falten.
-> - Si el archivo no existe, Intlayer lo generará usando la plantilla de archivo de declaración de contenido predeterminada.
+> - Si el archivo ya existe, Intlayer lo analizará usando el AST (Árbol de Sintaxis Abstracta) para localizar cada campo e insertar las traducciones faltantes.
+> - Si el archivo no existe, Intlayer lo generará usando la plantilla predeterminada de archivo de declaración de contenido.
 
 ## Rutas Absolutas
 
@@ -110,9 +110,9 @@ Esto generará el archivo en:
 /messages/example.content.json
 ```
 
-## Generar Automáticamente Archivos de Declaración de Contenido Por Localización
+## Autogenerar Archivos de Declaración de Contenido Por Localidad
 
-El campo `autoFill` también soporta la generación de archivos de declaración de contenido **por localización**.
+El campo `autoFill` también soporta la generación de archivos de declaración de contenido **por localidad**.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -132,9 +132,11 @@ Esto generará dos archivos separados:
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## Filtrar Auto-relleno por Localización Específica
+> En este caso, si el objeto no contiene todos los locales, Intlayer omitirá la generación de los locales restantes.
+
+## Filtrar Autocompletado para Locales Específicos
 
-Usar un objeto para el campo `autoFill` te permite aplicar filtros y generar solo archivos para localizaciones específicas.
+Usar un objeto para el campo `autoFill` te permite aplicar filtros y generar solo archivos para locales específicos.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -150,16 +152,17 @@ const exampleContent = {
 
 Esto solo generará el archivo de traducción en francés.
 
-## Variables en la Ruta
+## Variables de Ruta
 
 Puedes usar variables dentro de la ruta `autoFill` para resolver dinámicamente las rutas destino de los archivos generados.
 
 **Variables disponibles:**
 
-- `{{locale}}` – Código de localización (por ejemplo, `fr`, `es`)
+- `{{locale}}` – Código de la localidad (por ejemplo, `fr`, `es`)
+- `{{fileName}}` – Nombre del archivo (por ejemplo, `index`)
 - `{{key}}` – Clave del diccionario (por ejemplo, `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",
@@ -174,6 +177,25 @@ Esto generará:
 - `/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: {
+    // Tu contenido
+  },
+};
+```
+
+Esto generará:
+
+- `./index.content.json`
+- `./index.content.json`
+
 ## Historial de Documentación
 
-- 5.5.10 - 2025-06-29: Inicio del historial
+| Versión | Fecha      | Cambios                        |
+| ------- | ---------- | ------------------------------ |
+| 6.0.0   | 2025-09-20 | Añadir configuración global    |
+| 6.0.0   | 2025-09-17 | Añadir variable `{{fileName}}` |
+| 5.5.10  | 2025-06-29 | Historial inicial              |